find man page on Mageia

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

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

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

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  spe‐
	      cial  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(1P)
[top]

List of man pages available for Mageia

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