dirclean(8)dirclean(8)NAMEdirclean - Clean directories based on time and type criteria
SYNOPSIS
/usr/sbin/dirclean [-a|c|m|t [+|-]days]... [-k types] [-n] [-o] [-v]
[-D] dirlist
/usr/sbin/dirclean -H
OPTIONS
Sets the threshold for file removal in terms of the file's atime
(access time). Files are removed only if they were accessed more than
(+), less than (-), or exactly the specified number of whole days ago.
It is important to remember that the utility's threshold for
file removal is specified in terms of whole days whereas a
file's atime value is a timestamp that includes hours and min‐
utes (a partial day). The utility truncates the file's atime
timestamp to whole days. Therefore, +1 means that files that
were last accessed at least 48 hours before dirclean processing
will be removed. Specifying -1 means that files accessed less
than 24 hours before dirclean processing will be removed, and 1
means files that were last accessed at least 24 hours ago but
less than 48 hours ago will be removed. Sets the threshold for
file removal in terms of the file's ctime (inode change time).
Files are removed only if they have an inode change time that is
more than (+), less than (-), or exactly the specified number of
whole days.
See the description of the -a option for information about how
truncation of timestamp values affects specification of the
option argument. Specifies which types of filesystem objects to
keep. The types string can be zero or more letters from the fol‐
lowing list (chosen to match the -type option of the find com‐
mand): Keeps block-special files. Keeps character-special
files. Keeps directories. Keeps plain (regular) files. Keeps
symbolic links. Keeps named pipes ('fifos'). Keeps UNIX-domain
sockets.
Alternatively, you can use -k '' to specify that none of the
above are to be kept; in other words, -k '' specifies that all
files of the preceding types should be removed.
If the -k option is omitted from the command line, the default
is -k s (keep UNIX-domain sockets).
In all cases, dirclean removes directories only if they are
empty. Sets the threshold for file removal in terms of the
file's mtime (modification time). Files are removed only if they
were last modified more than (+), less than (-), or exactly the
specified number of whole days ago.
See the description of the -a option for information about how
truncation of timestamp values affects specification of the
option argument. No-removal mode. Tells which files would be
deleted by the command without actually deleting them. Specify‐
ing -n implicitly specifies -v (verbose mode). Skips (does not
remove) files that are open or otherwise in use by other pro‐
cesses. Simultaneously applies the [+|-]days argument to each
of the atime, ctime, and mtime options. The -t option is a
shorthand way of specifying the -a, -c, and -m options with
identical arguments. Verbose mode; lists all files removed.
Debug mode; lists why any target entries are not removed. Gives
an extended usage summary to standard output and exits success‐
fully.
OPERANDS
Specifies one or more pathnames (in a space-separated list) of starting
directories from which to recursively remove files. Pathnames may be
absolute or relative.
DESCRIPTION
The dirclean utility recursively removes files that meet the con‐
straints supplied by the option list. The utility is typically used to
clean out old files from directories, such as /tmp, that are used as
holding space for temporary files. The operation of this utility is
similar to that of the find and rm command combinations that are gener‐
ally used to remove stale file entries; however, dirclean removes files
more quickly and in a more secure manner than is possible with multi-
process solutions.
For each starting directory (as supplied by dirlist), the dirclean
utility recursively unlinks subordinate files that meet the constraints
given by the options, which may appear in any order; however, the util‐
ity does not traverse any subdirectories that lead into a different
file system.
You can specify both minimum and maximum age thresholds in terms of a
file's atime, ctime, and mtime values. This requires entering two
instances of the options that specify these thresholds to set the
range. However, an error results if you specify more than one maximum
and one minimum timestamp for any of the atime, ctime, or mtime set‐
tings. An error also results if the specified minimum exceeds the spec‐
ified maximum. (The combination of -a -1 and -a +1 is an example of
this error condition.)
If the command line does not contain any -a, -c, -m, or -t options,
target files are removed regardless of when they were created, modi‐
fied, or last accessed.
RESTRICTIONS
The dirclean utility is less flexible than the find and rm combinations
which it is intended to replace. Specifically, there is no way to give
dirclean a file exclusion list.
EXIT STATUS
Successfully traversed all the starting directories supplied by
dirlist. At least one removal operation failed during directory tra‐
versal. At least one pathname in dirlist was not a directory. A sys‐
tem call invoked by the utility failed unexpectedly. Incorrect argu‐
ments or another usage error was encountered.
ERRORS
The following diagnostics may be printed to standard error during the
normal course of utility operation. The message text shown in this ref‐
erence page includes printf() substitution directives, such as %c,
which are replaced with real values as explained in the message
description. However, a message shown with a trailing %m ends with the
standard strerror() text for a failure condition returned by an under‐
lying system call. The diagnostic descriptions do not discuss the sys‐
tem call failure messages that replace %m. See intro(2) for informa‐
tion about errors returned by system calls. Usage: dirclean [-{acmt}
[+-]days] [-k types] [-o] [-v] [-D] dirlist
An unrecognized option was encountered, or the dirlist argument
was omitted. dirclean: Invalid timestamp value for '-%c'
option: %s
The argument for one of the timestamp options (-a, -c, -m, or
-t) was not syntactically valid. The argument was not a string
of digits with an optional leading plus (+) or minus (-) . The
'-%c' directive is replaced with the option being parsed, and
the %s directive is replaced with the invalid argument.
dirclean: Out-of-range timestamp value for '-%c' option: %s
The argument (%s) for the -a, -c, -m, or -t option (-%c) maps to
a timestamp that is not supported in standard UNIX internal time
representation format. Typically, this error occurs when the
timestamp specifies a date and time before 1 January 1970.
dirclean: Timestamp value for '-%c' option conflicts with ear‐
lier values: %s
The argument (%s) to the -a, -c, -m, or -t option (%c) repre‐
sents a second attempt to set a removal threshold in terms of a
file's atime, ctime, or mtime value. dirclean: Timestamp con‐
straints for '-%c' option impossible to satisfy: %s
One of the timestamp options (%c) was specified twice, with both
a +days argument and a -days value, and the minimum value for
the corresponding timestamp exceeds the maximum allowed value.
The second instance of the argument that causes this condition
replaces %s. dirclean: Bad argument to -k option: valid types
are "bcdflps"
The -k option included an invalid letter in the types value.
(Try 'dirclean -H' for help.)
This message is appended to any of the preceding messages (all
of which note invalid command-line arguments) to remind the user
that the dirclean-H command displays usage information.
dirclean: Cannot open current directory: %m
For proper operation, the dirclean utility needs to open its
original directory ("."). This operation failed. dirclean:
Internal error: Invalid return (%d) from traversing directory:
%s
This message should never occur, as it indicates an internal
logic error in the utility. Please report any occurrence of this
message, along with a way to reproduce the problem, to your sup‐
port representative or submit a Software Problem Report (SPR)
that contains this information. dirclean: lstat failure for
starting directory: %s: %m
One of the starting directories (%s) specified in dirlist does
not exist or is not accessible. dirclean: Starting directory
argument is not a directory: %s
One of the starting directories (%s) included in dirlist is not
a directory. dirclean: Cannot fchdir() back to original direc‐
tory after processing "%s" argument: %m
After recursively processing a starting directory (%s) in
dirlist, an error occurred when the utility attempted to change
directory back to its original location. (The utility changes
directory back to its original location after processing each
operand to ensure correct location should a subsequent operand
be specified as a relative path). dirclean: Cannot allocate
space to process directory: %s: %m
An error occurred when the utility made a system call to allo‐
cate space for holding a constructed pathname (%s). This error
indicates that process data size limits or system paging space
are unusually low. dirclean: Cannot open directory: %s: %m
The indicated directory (%s) could not be opened in order to
traverse its entries. dirclean: Directory moved during process‐
ing (skipped): %s
The indicated directory (%s) changed between the time the util‐
ity parsed and saved the pathname operand and the time the util‐
ity attempted to open that directory for processing. This error
does not occur if a directory was updated in a normal manner;
the error means that the directory being opened was not the same
directory as specified by the saved pathname. The volatility of
the directory indicates that processing it might not be safe;
therefore, the utility skipped over it to process the next oper‐
and, if any. dirclean: Cannot fchdir() to process directory:
%s: %m
The utility could not change location to the indicated directory
(%s) to start processing after the directory was successfully
opened. (This error usually means that the directory's permis‐
sions allow reading but not searching.) dirclean: Cannot
lstat() directory entry: %s: %m
An attempt to verify the file type of a pathname operand (%s)
failed. dirclean: Cannot fchdir() back to directory "%s" after
processing sub-directory entry: %s: %m
An attempt to return to a previous directory level failed. The
first %s indicates the parent directory for which the fchdir()
system call failed, and the second %s indicates the subdirectory
that the utility had just finished processing. dirclean:
Removed directory %s
An empty directory was successfully removed. This message
appears only if the -v option is specified. dirclean: Cannot
unlink %s: %m
An attempt to remove the specified pathname (%s) failed.
dirclean: Unlinked %s
The indicated pathname was successfully removed. This message
appears only if the -v option is specified. dirclean: Cannot
rmdir %s: %m
An attempt to remove a directory (%s) failed for some reason
other than condition that the directory was not empty.
dirclean: Failed in fuser() check of %s: %m
The -o option was specified and when the utility was checking to
see if the indicated file (%s) was in use, an unexpected error
was encountered. dirclean: utimes() failure for directory %s:
%m
When trying to restore the timestamps for the specified direc‐
tory (%s), an unexpected error was encountered.
The dirclean utility may issue the following additional diagnostics
when the -D (debug) option is in effect: Skipped entry: %s\n\tReason:
%s
This is the top-level debug message. The indicated file (the
first %s) is not being removed for the reason given by the
trailing %s. That reason will be one of the following: Rejected
by time-stamp constraints
One of the timestamp options (-a, -c, -m, or -t) was specified,
and the corresponding timestamps on the indicated file were
rejected by those constraints. This type of file is to be pre‐
served
Either the indicated file is a UNIX-domain socket and -k option
was not specified, or the file is one that an explicit -k option
marked for preservation. Directory is the start of a different
file system
Descending into the indicated directory would require crossing
filesystem boundaries. Doing so is not supported by this util‐
ity. Directory is not empty
An attempt to remove a directory failed because the directory
was not empty. File or directory is in use by another process
The -o option was specified and the indicated file is open or
otherwise in use by another process.
EXAMPLES
The following commands, which are included by default in the root
user's crontab entry by current releases of the operating system, clean
out the /tmp and /var/tmp directories:
/usr/sbin/dirclean -a +2 /tmp/ /usr/sbin/dirclean -a +7
/var/tmp/
These entries replaced the find and rm invocations included in
that crontab entry by older releases of the operating system.
(For complete emulation of the former crontab entries, these
dirclean commands should include -k bcdlps in addition to the
options shown.) The following command removes empty directories
from a directory tree ($MYDIR):
/usr/sbin/dirclean -k bcflps $MYDIR
This dirclean command is equivalent to the following combination
of find and rmdir commands:
find $MYDIR -mount -depth -type d -exec rmdir {} \; In prepara‐
tion for recompiling files in a large project, the following
command removes all entries from an object file directory (objs)
but keeps the directory itself:
/usr/sbin/dirclean -k '' objs
ENVIRONMENT VARIABLES
Provides a default value for the internationalization variables that
are unset or null. If LANG is unset or null, the corresponding value
from the default locale is used. If any of the internationalization
variables contain an invalid setting, the utility behaves as if none of
the variables had been defined. If set to a non-empty string value,
overrides the values of all the other internationalization variables.
Determines the locale for the format and contents of diagnostic mes‐
sages written to standard error. Determines the location of message
catalogs for the processing of LC_MESSAGES.
SEE ALSO
Commands: find(1), rm(1), rmdir(1), xargs(1)
Functions: fchdir(2), fuser(2), lstat(2), rmdir(2), unlink(2),
utimes(2)dirclean(8)