find man page on YellowDog

Man page or keyword search:  
man Server   18644 pages
apropos Keyword Search (all sections)
Output format
YellowDog logo
[printable version]

FIND(P)			   POSIX Programmer's Manual		       FIND(P)

NAME
       find - find files

SYNOPSIS
       find [-H | -L] path ... [operand_expression ...]

DESCRIPTION
       The find utility shall recursively descend the directory hierarchy from
       each file specified by path, evaluating a Boolean  expression  composed
       of  the	primaries  described  in  the  OPERANDS	 section for each file
       encountered.

       The find utility shall be able to descend to arbitrary depths in a file
       hierarchy  and  shall not fail due to path length limitations (unless a
       path operand specified by the application exceeds  {PATH_MAX}  require‐
       ments).

       The  find utility shall detect infinite loops; that is, entering a pre‐
       viously visited directory that is an ancestor of the last file  encoun‐
       tered.  When it detects an infinite loop, find shall write a diagnostic
       message to standard error and shall either recover its position in  the
       hierarchy or terminate.

OPTIONS
       The  find  utility  shall  conform  to  the  Base Definitions volume of
       IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.

       The following options shall be supported by the implementation:

       -H     Cause the file information and file type evaluated for each sym‐
	      bolic  link  encountered	on the command line to be those of the
	      file referenced by the link, and not the	link  itself.  If  the
	      referenced  file	does  not exist, the file information and type
	      shall be for the link itself. File information for all  symbolic
	      links not on the command line shall be that of the link itself.

       -L     Cause the file information and file type evaluated for each sym‐
	      bolic link to be those of the file referenced by the  link,  and
	      not the link itself.

       Specifying  more	 than  one of the mutually-exclusive options -H and -L
       shall not be considered an  error.  The	last  option  specified	 shall
       determine the behavior of the utility.

OPERANDS
       The following operands shall be supported:

       The  path  operand  is  a pathname of a starting point in the directory
       hierarchy.

       The first argument that starts with a '-' , or is a '!'	or a '(' , and
       all  subsequent arguments shall be interpreted as an expression made up
       of the following primaries and operators. In the descriptions, wherever
       n  is  used as a primary argument, it shall be interpreted as a decimal
       integer optionally preceded by a plus ( '+' ) or minus ( '-' ) sign, as
       follows:

       +n     More than n.

       n      Exactly n.

       -n     Less than n.

       The following primaries shall be supported:

       -name  pattern

	      The  primary shall evaluate as true if the basename of the file‐
	      name being examined matches pattern using the  pattern  matching
	      notation described in Pattern Matching Notation .

       -nouser
	      The primary shall evaluate as true if the file belongs to a user
	      ID for which the	getpwuid()  function  defined  in  the	System
	      Interfaces   volume   of	IEEE Std 1003.1-2001  (or  equivalent)
	      returns NULL.

       -nogroup
	      The primary shall evaluate as true if  the  file	belongs	 to  a
	      group ID for which the getgrgid() function defined in the System
	      Interfaces  volume  of  IEEE Std 1003.1-2001   (or   equivalent)
	      returns NULL.

       -xdev  The  primary  shall always evaluate as true; it shall cause find
	      not to continue descending past directories that have a  differ‐
	      ent  device  ID ( st_dev, see the stat() function defined in the
	      System Interfaces volume of IEEE Std 1003.1-2001). If any	 -xdev
	      primary  is  specified,  it shall apply to the entire expression
	      even if the -xdev primary would not normally be evaluated.

       -prune The primary shall always evaluate as true; it shall  cause  find
	      not  to  descend	the current pathname if it is a directory.  If
	      the -depth primary is specified, the -prune primary  shall  have
	      no effect.

       -perm [-]mode

	      The  mode argument is used to represent file mode bits. It shall
	      be identical in format to the symbolic_mode operand described in
	      chmod() , and shall be interpreted as follows.  To start, a tem‐
	      plate shall be assumed with all file mode bits  cleared.	An  op
	      symbol  of  '+'  shall set the appropriate mode bits in the tem‐
	      plate; '-' shall clear the appropriate bits; '=' shall  set  the
	      appropriate  mode	 bits,	without	 regard	 to  the  contents  of
	      process' file mode creation mask. The op symbol of '-' cannot be
	      the  first  character  of	 mode;	this avoids ambiguity with the
	      optional leading hyphen. Since the initial mode is all bits off,
	      there  are  not  any  symbolic modes that need to use '-' as the
	      first character.

       If the hyphen is omitted, the primary shall evaluate as true  when  the
       file permission bits exactly match the value of the resulting template.

       Otherwise,  if mode is prefixed by a hyphen, the primary shall evaluate
       as true if at least all the bits in the resulting template are  set  in
       the file permission bits.

       -perm [-]onum

	      If  the  hyphen  is  omitted, the primary shall evaluate as true
	      when the file permission bits exactly match  the	value  of  the
	      octal  number  onum and only the bits corresponding to the octal
	      mask 07777 shall be compared. (See the description of the	 octal
	      mode  in	chmod() .) Otherwise, if onum is prefixed by a hyphen,
	      the primary shall evaluate as true if at least all of  the  bits
	      specified	 in onum that are also set in the octal mask 07777 are
	      set.

       -type  c
	      The primary shall evaluate as true if the type of the file is c,
	      where  c is 'b' , 'c' , 'd' , 'l' , 'p' , 'f' , or 's' for block
	      special file, character special file, directory, symbolic	 link,
	      FIFO, regular file, or socket, respectively.

       -links  n
	      The primary shall evaluate as true if the file has n links.

       -user  uname
	      The  primary  shall  evaluate as true if the file belongs to the
	      user uname. If uname is a decimal integer and the getpwnam() (or
	      equivalent)  function  does  not return a valid user name, uname
	      shall be interpreted as a user ID.

       -group  gname

	      The primary shall evaluate as true if the file  belongs  to  the
	      group  gname.  If	 gname is a decimal integer and the getgrnam()
	      (or equivalent) function does not return	a  valid  group	 name,
	      gname shall be interpreted as a group ID.

       -size  n[c]
	      The  primary  shall  evaluate as true if the file size in bytes,
	      divided by 512 and rounded up to the next integer, is n.	 If  n
	      is followed by the character 'c' , the size shall be in bytes.

       -atime  n
	      The  primary shall evaluate as true if the file access time sub‐
	      tracted from the initialization time, divided by 86400 (with any
	      remainder discarded), is n.

       -ctime  n
	      The primary shall evaluate as true if the time of last change of
	      file status information subtracted from the initialization time,
	      divided by 86400 (with any remainder discarded), is n.

       -mtime  n
	      The primary shall evaluate as true if the file modification time
	      subtracted from the initialization time, divided by 86400	 (with
	      any remainder discarded), is n.

       -exec  utility_name  [argument ...] ;

       -exec  utility_name  [argument ...]
	      {} +

	      The end of the primary expression shall be punctuated by a semi‐
	      colon or by a plus sign. Only a plus sign that follows an	 argu‐
	      ment  containing the two characters "{}" shall punctuate the end
	      of the primary expression. Other uses of the plus sign shall not
	      be treated as special.

       If  the	primary	 expression  is punctuated by a semicolon, the utility
       utility_name shall be invoked once for each pathname  and  the  primary
       shall evaluate as true if the utility returns a zero value as exit sta‐
       tus. A utility_name or argument containing only the two characters "{}"
       shall be replaced by the current pathname.

       If  the	primary	 expression  is punctuated by a plus sign, the primary
       shall always evaluate as true, and the pathnames for which the  primary
       is  evaluated  shall  be aggregated into sets. The utility utility_name
       shall be invoked once for each set of aggregated pathnames. Each	 invo‐
       cation  shall  begin  after the last pathname in the set is aggregated,
       and shall be completed before the find utility  exits  and  before  the
       first pathname in the next set (if any) is aggregated for this primary,
       but it is otherwise unspecified whether the invocation  occurs  before,
       during,	or after the evaluations of other primaries. If any invocation
       returns a non-zero value as exit status, the find utility shall	return
       a  non-zero exit status. An argument containing only the two characters
       "{}" shall be replaced by the set of aggregated	pathnames,  with  each
       pathname	 passed	 as  a separate argument to the invoked utility in the
       same order that it was aggregated.  The size of any set of two or  more
       pathnames  shall be limited such that execution of the utility does not
       cause the system's {ARG_MAX} limit to be exceeded.  If  more  than  one
       argument containing only the two characters "{}" is present, the behav‐
       ior is unspecified.

       If a utility_name or argument string contains the two characters "{}" ,
       but  not	 just  the  two characters "{}" , it is implementation-defined
       whether find replaces those two characters or uses the  string  without
       change.	The current directory for the invocation of utility_name shall
       be the same as the current directory when the find utility was started.
       If  the	utility_name  names any of the special built-in utilities (see
       Special Built-In Utilities ), the results are undefined.

       -ok  utility_name  [argument ...] ;

	      The -ok primary shall be equivalent to -exec,  except  that  the
	      use  of  a plus sign to punctuate the end of the primary expres‐
	      sion need not be supported, and find shall  request  affirmation
	      of  the  invocation of utility_name using the current file as an
	      argument by writing to standard error as described in the STDERR
	      section.	If  the response on standard input is affirmative, the
	      utility shall be invoked. Otherwise, the command	shall  not  be
	      invoked and the value of the -ok operand shall be false.

       -print The  primary  shall  always evaluate as true; it shall cause the
	      current pathname to be written to standard output.

       -newer  file
	      The primary shall evaluate as true if the modification  time  of
	      the  current  file  is more recent than the modification time of
	      the file named by the pathname file.

       -depth The primary shall	 always	 evaluate  as  true;  it  shall	 cause
	      descent  of  the	directory  hierarchy  to  be  done so that all
	      entries in a directory are acted on before the directory itself.
	      If a -depth primary is not specified, all entries in a directory
	      shall be acted on after the directory itself. If any -depth pri‐
	      mary  is specified, it shall apply to the entire expression even
	      if the -depth primary would not normally be evaluated.

       The primaries can be combined using the following operators  (in	 order
       of decreasing precedence):

       ( expression )
	      True if expression is true.

       !  expression
	      Negation of a primary; the unary NOT operator.

       expression  [-a]	 expression

	      Conjunction  of  primaries;  the	AND operator is implied by the
	      juxtaposition of two primaries or made explicit by the  optional
	      -a operator. The second expression shall not be evaluated if the
	      first expression is false.

       expression  -o  expression

	      Alternation of primaries; the OR operator. The second expression
	      shall not be evaluated if the first expression is true.

       If  no  expression  is present, -print shall be used as the expression.
       Otherwise, if the given expression does not contain  any	 of  the  pri‐
       maries -exec, -ok, or -print, the given expression shall be effectively
       replaced by:

	      ( given_expression ) -print

       The -user, -group, and  -newer  primaries  each	shall  evaluate	 their
       respective arguments only once.

STDIN
       If  the	-ok primary is used, the response shall be read from the stan‐
       dard input. An entire line shall be read as  the	 response.  Otherwise,
       the standard input shall not be used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of find:

       LANG   Provide  a  default value for the internationalization variables
	      that are unset or null. (See  the	 Base  Definitions  volume  of
	      IEEE Std 1003.1-2001,  Section  8.2,  Internationalization Vari‐
	      ables for the precedence of internationalization variables  used
	      to determine the values of locale categories.)

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

       LC_COLLATE

	      Determine the locale for the  behavior  of  ranges,  equivalence
	      classes, and multi-character collating elements used in the pat‐
	      tern matching notation for the -n option	and  in	 the  extended
	      regular expression defined for the yesexpr locale keyword in the
	      LC_MESSAGES category.

       LC_CTYPE
	      This variable determines the locale for  the  interpretation  of
	      sequences of bytes of text data as characters (for example, sin‐
	      gle-byte as opposed to multi-byte characters in arguments),  the
	      behavior	of character classes within the pattern matching nota‐
	      tion used for the -n  option,  and  the  behavior	 of  character
	      classes  within regular expressions used in the extended regular
	      expression defined for the yesexpr locale keyword in the LC_MES‐
	      SAGES category.

       LC_MESSAGES
	      Determine the locale for the processing of affirmative responses
	      that should be used to affect the format and contents  of	 diag‐
	      nostic messages written to standard error.

       NLSPATH
	      Determine the location of message catalogs for the processing of
	      LC_MESSAGES .

       PATH   Determine the location of the utility_name for the -exec and -ok
	      primaries,  as  described	 in  the  Base	Definitions  volume of
	      IEEE Std 1003.1-2001, Chapter 8, Environment Variables.

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       The -print primary shall cause the current pathnames to be  written  to
       standard output. The format shall be:

	      "%s\n", <path>

STDERR
       The  -ok	 primary  shall write a prompt to standard error containing at
       least the utility_name to be invoked and the current pathname.  In  the
       POSIX  locale,  the  last non- <blank> in the prompt shall be '?' . The
       exact format used is unspecified.

       Otherwise, the standard error shall be used only	 for  diagnostic  mes‐
       sages.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       The following exit values shall be returned:

	0     All path operands were traversed successfully.

       >0     An error occurred.

CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       When  used  in operands, pattern matching notation, semicolons, opening
       parentheses, and closing parentheses are special to the shell and  must
       be quoted (see Quoting ).

       The  bit	 that is traditionally used for sticky (historically 01000) is
       specified in the -perm primary using the octal  number  argument	 form.
       Since  this  bit is not defined by this volume of IEEE Std 1003.1-2001,
       applications must not assume that it actually refers to the traditional
       sticky bit.

EXAMPLES
	1. The following commands are equivalent:

	   find .
	   find . -print

       They  both  write  out  the entire directory hierarchy from the current
       directory.

	2. The following command:

	   find / \( -name tmp -o -name '*.xx' \) -atime +7 -exec rm {} \;

       removes all files named tmp  or	ending	in  .xx	 that  have  not  been
       accessed for seven or more 24-hour periods.

	3. The following command:

	   find . -perm -o+w,+s

       prints ( -print is assumed) the names of all files in or below the cur‐
       rent directory, with all of the file permission bits S_ISUID,  S_ISGID,
       and S_IWOTH set.

	4. The following command:

	   find . -name SCCS -prune -o -print

       recursively  prints pathnames of all files in the current directory and
       below, but skips directories named SCCS and files in them.

	5. The following command:

	   find . -print -name SCCS -prune

       behaves as in the previous example, but prints the names	 of  the  SCCS
       directories.

	6. The following command is roughly equivalent to the -nt extension to
	   test:

	   if [ -n "$(find file1 -prune -newer file2)" ]; then
	       printf %s\\n "file1 is newer than file2"
	   fi

	7. The descriptions of -atime, -ctime, and -mtime use the  terminology
	   n  "86400  second  periods (days)". For example, a file accessed at
	   23:59 is selected by:

	   find . -atime -1 -print

       at 00:01 the next day (less than 24 hours later, not more than one  day
       ago);  the  midnight boundary between days has no effect on the 24-hour
       calculation.

RATIONALE
       The -a operator was retained as an optional operator for	 compatibility
       with historical shell scripts, even though it is redundant with expres‐
       sion concatenation.

       The descriptions of the '-' modifier on the mode and onum arguments  to
       the  -perm  primary  agree with historical practice on BSD and System V
       implementations. System V and BSD documentation	both  describe	it  in
       terms  of checking additional bits; in fact, it uses the same bits, but
       checks for having at least all of the matching bits set instead of hav‐
       ing exactly the matching bits set.

       The  exact  format  of the interactive prompts is unspecified. Only the
       general nature of the contents of prompts are specified because:

	* Implementations may desire more descriptive prompts than those  used
	  on historical implementations.

	* Since	 the  historical  prompt  strings  do not terminate with <new‐
	  line>s, there is no portable way for	another	 program  to  interact
	  with the prompts of this utility via pipes.

       Therefore,  an  application  using  this prompting option relies on the
       system to provide the most suitable  dialog  directly  with  the	 user,
       based on the general guidelines specified.

       The  -name  file	 operand was changed to use the shell pattern matching
       notation so that find is consistent with other utilities using  pattern
       matching.

       The  -size operand refers to the size of a file, rather than the number
       of blocks it may occupy in the file system.  The	 intent	 is  that  the
       st_size	 field	 defined   in	the   System   Interfaces   volume  of
       IEEE Std 1003.1-2001 should be used, not the st_blocks found in histor‐
       ical implementations. There are at least two reasons for this:

	1. In  both  System V and BSD, find only uses st_size in size calcula‐
	   tions   for	 the   operands	  specified   by   this	  volume    of
	   IEEE Std 1003.1-2001.  (BSD uses st_blocks only when processing the
	   -ls primary.)

	2. Users usually think of file size in terms of bytes, which  is  also
	   the	unit used by the ls utility for the output from the -l option.
	   (In both System V and BSD, ls uses st_size for the -l  option  size
	   field and uses st_blocks for the ls -s calculations. This volume of
	   IEEE Std 1003.1-2001 does not specify ls -s.)

       The descriptions of -atime, -ctime, and -mtime were  changed  from  the
       SVID  description of n "days'' to "24-hour periods". The description is
       also different in terms of the exact timeframe for the n	 case  (versus
       the +n or -n), but it matches all known historical implementations.  It
       refers to one 86400 second period in the past, not any  time  from  the
       beginning  of that period to the current time. For example, -atime 3 is
       true if the file was accessed any time in the period from 72  hours  to
       48 hours ago.

       Historical implementations do not modify "{}" when it appears as a sub‐
       string of an -exec or -ok utility_name or argument string.  There  have
       been  numerous  user  requests  for  this  extension, so this volume of
       IEEE Std 1003.1-2001 allows the desired behavior. At least  one	recent
       implementation does support this feature, but encountered several prob‐
       lems in managing memory allocation and  dealing	with  multiple	occur‐
       rences  of  "{}" in a string while it was being developed, so it is not
       yet required behavior.

       Assuming the presence of -print was added to correct a historical  pit‐
       fall  that plagues novice users, it is entirely upwards-compatible from
       the historical System V find utility.  In  its  simplest	 form  (  find
       directory), it could be confused with the historical BSD fast find. The
       BSD developers agreed that adding -print as a  default  expression  was
       the  correct decision and have added the fast find functionality within
       a new utility called locate.

       Historically, the -L option was implemented using the primary  -follow.
       The  -H	and -L options were added for two reasons. First, they offer a
       finer granularity of control and consistency with other	programs  that
       walk  file hierarchies. Second, the -follow primary always evaluated to
       true. As they were  historically	 really	 global	 variables  that  took
       effect  before  the  traversal  began, some valid expressions had unex‐
       pected results. An example is the expression -print -o -follow. Because
       -print  always  evaluates  to  true,  the  standard order of evaluation
       implies that -follow would never be evaluated. This was never the case.
       Historical  practice  for  the -follow primary, however, is not consis‐
       tent. Some implementations always follow symbolic links on the  command
       line whether -follow is specified or not.  Others follow symbolic links
       on the command line only if -follow is specified.  Both	behaviors  are
       provided	 by the -H and -L options, but scripts using the current -fol‐
       low primary would be broken if the -follow option is specified to  work
       either way.

       Since the -L option resolves all symbolic links and the -type l primary
       is true for symbolic links that still exist after symbolic  links  have
       been resolved, the command:

	      find -L . -type l

       prints  a  list	of symbolic links reachable from the current directory
       that do not resolve to accessible files.

       A feature of SVR4's find utility was the -exec primary's +  terminator.
       This  allowed filenames containing special characters (especially <new‐
       line>s) to be grouped together without the problems that occur if  such
       filenames  are  piped  to xargs. Other implementations have added other
       ways to get around this problem, notably a -print0 primary  that	 wrote
       filenames  with	a  null byte terminator. This was considered here, but
       not adopted. Using a null terminator meant that any  utility  that  was
       going to process find's -print0 output had to add a new option to parse
       the null terminators it would now be reading.

       The "-exec ... {} +" syntax adopted was a result of IEEE PASC Interpre‐
       tation  1003.2  #210.  It  should be noted that this is an incompatible
       change to the ISO/IEC 9899:1999 standard. For  example,	the  following
       command	prints all files with a '-' after their name if they are regu‐
       lar files, and a '+' otherwise:

	      find / -type f -exec echo {} - ';' -o -exec echo {} + ';'

       The change invalidates usage like this. Even though the previous	 stan‐
       dard  stated  that this usage would work, in practice many did not sup‐
       port it and the standard developers felt it better to  now  state  that
       this was not allowable.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Quoting	,  Pattern  Matching  Notation	, Special Built-In Utilities ,
       chmod()	,  pax	,  sh  ,  test	,  the	System	Interfaces  volume  of
       IEEE Std 1003.1-2001, getgrgid(), getpwuid(), stat()

COPYRIGHT
       Portions	 of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating	System	Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003	by  the	 Institute  of
       Electrical  and	Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained	online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group		     2003			       FIND(P)
[top]

List of man pages available for YellowDog

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net