unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



dirclean(8)							  dirclean(8)
Patchkit 3							   Patchkit 3



NAME

  dirclean - 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

  -a [+|-]days
      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	remo-
      val is specified in terms	of whole days whereas a	file's atime value is
      a	timestamp that includes	hours and minutes (a partial day). The util-
      ity truncates the	file's atime timestamp to whole	days.  Therefore, +1
      means that files that were last accessed at least	48 hours before	dir-
      clean 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.

  -c [+|-]days
      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 trunca-
      tion of timestamp	values affects specification of	the option argument.

  -k types
      Specifies	which types of filesystem objects to keep. The types string
      can be zero or more letters from the following list (chosen to match
      the -type	option of the find command):

      b	  Keeps	block-special files.

      c	  Keeps	character-special files.

      d	  Keeps	directories.

      f	  Keeps	plain (regular)	files.

      l	  Keeps	symbolic links.

      p	  Keeps	named pipes ('fifos').

      s	  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.

  -m [+|-]days
      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 trunca-
      tion of timestamp	values affects specification of	the option argument.

  -n  No-removal mode. Tells which files would be deleted by the command
      without actually deleting	them. Specifying -n implicitly specifies -v
      (verbose mode).

  -o  Skips (does not remove) files that are open or otherwise in use by
      other processes.

  -t [+|-]days
      Simultaneously applies the [+|-]days argument to each of the atime,
      ctime, and mtime options.	The -t option is a shorthand way of specify-
      ing the -a, -c, and -m options with identical arguments.

  -v  Verbose mode; lists all files removed.

  -D  Debug mode; lists	why any	target entries are not removed.

  -H  Gives an extended	usage summary to standard output and exits success-
      fully.

OPERANDS

  dirlist
      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 constraints
  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 generally 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 utility 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 times-
  tamp for any of the atime, ctime, or mtime settings. An error	also results
  if the specified minimum exceeds the specified 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, modified, 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 dir-
  clean	a file exclusion list.

EXIT STATUS

  0 (Zero)
	  Successfully traversed all the starting directories supplied by
	  dirlist.

  1	  At least one removal operation failed	during directory traversal.

  2	  At least one pathname	in dirlist was not a directory.

  3	  A system call	invoked	by the utility failed unexpectedly.

  4	  Incorrect arguments or another usage error was encountered.

ERRORS

  The following	diagnostics may	be printed to standard error during the	nor-
  mal course of	utility	operation. The message text shown in this reference
  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 underlying system call. The diagnos-
  tic descriptions do not discuss the system call failure messages that
  replace %m.  See intro(2) for	information 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 earlier
       values: %s

       The argument (%s) to the	-a, -c,	-m, or -t option (%c) represents a
       second attempt to set a removal threshold in terms of a file's atime,
       ctime, or mtime value.

    +  dirclean: Timestamp constraints 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 direc-
       tory: %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 support representa-
       tive 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 directory 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 ori-
       ginal location after processing each operand to ensure correct loca-
       tion 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	allocate
       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	processing (skipped): %s

       The indicated directory (%s) changed between the	time the utility
       parsed and saved	the pathname operand and the time the utility
       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 speci-
       fied 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 operand, 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 permissions allow	read-
       ing 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 encoun-
       tered.

    +  dirclean: utimes() failure for directory	%s: %m

       When trying to restore the timestamps for the specified directory
       (%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 preserved

       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	utility.

    +  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 other-
       wise in use by another process.

EXAMPLES

   1.  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.)

   2.  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 {} \;

   3.  In preparation 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

  LANG
      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.

  LC_ALL
      If set to	a non-empty string value, overrides the	values of all the
      other internationalization variables.

  LC_MESSAGES
      Determines the locale for	the format and contents	of diagnostic mes-
      sages written to standard	error.

  NLSPATH
      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)

  Others: intro(2)