find.1p (30066B)
- '\" et
- .TH FIND "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH 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.
- .\"
- .SH NAME
- find
- \(em find files
- .SH SYNOPSIS
- .LP
- .nf
- find \fB[\fR-H|-L\fB] \fIpath\fR... \fB[\fIoperand_expression\fR...\fB]
- .fi
- .SH DESCRIPTION
- The
- .IR find
- utility shall recursively descend the directory hierarchy from each
- file specified by
- .IR path ,
- evaluating a Boolean expression composed of the primaries described in
- the OPERANDS section for each file encountered. Each
- .IR path
- operand shall be evaluated unaltered as it was provided, including
- all trailing
- <slash>
- characters; all pathnames for other files encountered in the hierarchy
- shall consist of the concatenation of the current
- .IR path
- operand, a
- <slash>
- if the current
- .IR path
- operand did not end in one, and the filename relative to the
- .IR path
- operand. The relative portion shall contain no dot or dot-dot components,
- no trailing
- <slash>
- characters, and only single
- <slash>
- characters between pathname components.
- .P
- The
- .IR 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
- .IR path
- operand specified by the application exceeds
- {PATH_MAX}
- requirements).
- .P
- The
- .IR find
- utility shall detect infinite loops; that is, entering a previously
- visited directory that is an ancestor of the last file encountered.
- When it detects an infinite loop,
- .IR find
- shall write a diagnostic message to standard error and shall either
- recover its position in the hierarchy or terminate.
- .P
- If a file is removed from or added to the directory hierarchy being
- searched it is unspecified whether or not
- .IR find
- includes that file in its search.
- .SH OPTIONS
- The
- .IR find
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The following options shall be supported by the implementation:
- .IP "\fB\-H\fP" 10
- Cause the file information and file type evaluated for each symbolic
- link encountered as a
- .IR path
- operand 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
- and type for symbolic links encountered during the traversal of a file
- hierarchy shall be that of the link itself.
- .IP "\fB\-L\fP" 10
- Cause the file information and file type evaluated for each symbolic
- link encountered as a
- .IR path
- operand on the command line or encountered during the traversal of
- a file hierarchy 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.
- .P
- Specifying more than one of the mutually-exclusive options
- .BR \-H
- and
- .BR \-L
- shall not be considered an error. The last option specified shall
- determine the behavior of the utility. If neither the
- .BR \-H
- nor the
- .BR \-L
- option is specified, then the file information and type for symbolic
- links encountered as a
- .IR path
- operand on the command line or encountered during the traversal of a
- file hierarchy shall be that of the link itself.
- .SH OPERANDS
- The following operands shall be supported:
- .P
- The first operand and subsequent operands up to but not including the
- first operand that starts with a
- .BR '\-' ,
- or is a
- .BR '!'
- or a
- .BR '(' ,
- shall be interpreted as
- .IR path
- operands. If the first operand starts with a
- .BR '\-' ,
- or is a
- .BR '!'
- or a
- .BR '(' ,
- the behavior is unspecified. Each
- .IR path
- operand is a pathname of a starting point in the file hierarchy.
- .P
- The first operand that starts with a
- .BR '\-' ,
- or is a
- .BR '!'
- or a
- .BR '(' ,
- and all subsequent arguments shall be interpreted as an
- .IR expression
- made up of the following primaries and operators. In the descriptions,
- wherever
- .IR n
- is used as a primary argument, it shall be interpreted as a decimal
- integer optionally preceded by a
- <plus-sign>
- (\c
- .BR '\(pl' )
- or
- <hyphen-minus>
- (\c
- .BR '\-' ),
- as follows:
- .IP "+\fIn\fR" 10
- More than
- .IR n .
- .IP "\fIn\fR" 10
- Exactly
- .IR n .
- .IP "\-\fIn\fR" 10
- Less than
- .IR n .
- .P
- The following primaries shall be supported:
- .IP "\fB\-name\ \fIpattern\fR" 10
- .br
- The primary shall evaluate as true if the basename of the current
- pathname matches
- .IR pattern
- using the pattern matching notation described in
- .IR "Section 2.13" ", " "Pattern Matching Notation".
- The additional rules in
- .IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion"
- do not apply as this is a matching operation, not an expansion.
- .IP "\fB\-path\ \fIpattern\fR" 10
- .br
- The primary shall evaluate as true if the current pathname matches
- .IR pattern
- using the pattern matching notation described in
- .IR "Section 2.13" ", " "Pattern Matching Notation".
- The additional rules in
- .IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion"
- do not apply as this is a matching operation, not an expansion.
- .IP "\fB\-nouser\fP" 10
- The primary shall evaluate as true if the file belongs to a user ID for
- which the
- \fIgetpwuid\fR()
- function defined in the System Interfaces volume of POSIX.1\(hy2017 (or equivalent) returns NULL.
- .IP "\fB\-nogroup\fP" 10
- The primary shall evaluate as true if the file belongs to a group ID
- for which the
- \fIgetgrgid\fR()
- function defined in the System Interfaces volume of POSIX.1\(hy2017 (or equivalent) returns NULL.
- .IP "\fB\-xdev\fP" 10
- The primary shall always evaluate as true; it shall cause
- .IR find
- not to continue descending past directories that have a different
- device ID (\c
- .IR st_dev ,
- see the
- \fIstat\fR()
- function defined in the System Interfaces volume of POSIX.1\(hy2017). If any
- .BR \-xdev
- primary is specified, it shall apply to the entire expression even if
- the
- .BR \-xdev
- primary would not normally be evaluated.
- .IP "\fB\-prune\fP" 10
- The primary shall always evaluate as true; it shall cause
- .IR find
- not to descend the current pathname if it is a directory. If the
- .BR \-depth
- primary is specified, the
- .BR \-prune
- primary shall have no effect.
- .IP "\fB\-perm\ [\-]\fImode\fR" 10
- .br
- The
- .IR mode
- argument is used to represent file mode bits. It shall be identical in
- format to the
- .IR symbolic_mode
- operand described in
- .IR chmod ,
- and shall be interpreted as follows. To start, a template shall be
- assumed with all file mode bits cleared. An
- .IR op
- symbol of
- .BR '\(pl'
- shall set the appropriate mode bits in the template;
- .BR '\-'
- shall clear the appropriate bits;
- .BR '='
- shall set the appropriate mode bits, without regard to the contents of
- the file mode creation mask of the process. The
- .IR op
- symbol of
- .BR '\-'
- cannot be the first character of
- .IR mode ;
- this avoids ambiguity with the optional leading
- <hyphen-minus>.
- Since the initial mode is all bits off, there are not any symbolic modes
- that need to use
- .BR '\-'
- as the first character.
- .RS 10
- .P
- If the
- <hyphen-minus>
- is omitted, the primary shall evaluate as true when the file permission
- bits exactly match the value of the resulting template.
- .P
- Otherwise, if
- .IR mode
- is prefixed by a
- <hyphen-minus>,
- the primary shall evaluate as true if at least all the bits in the
- resulting template are set in the file permission bits.
- .RE
- .IP "\fB\-perm\ [\-]\fIonum\fR" 10
- .br
- If the
- <hyphen-minus>
- is omitted, the primary shall evaluate as true when the file mode bits
- exactly match the value of the octal number
- .IR onum
- (see the description of the octal
- .IR mode
- in
- .IR chmod ).
- Otherwise, if
- .IR onum
- is prefixed by a
- <hyphen-minus>,
- the primary shall evaluate as true if at least all of the bits specified in
- .IR onum
- are set. In both cases, the behavior is unspecified when
- .IR onum
- exceeds 07777.
- .IP "\fB\-type\ \fIc\fR" 10
- The primary shall evaluate as true if the type of the file is
- .IR c ,
- where
- .IR c
- is
- .BR 'b' ,
- .BR 'c' ,
- .BR 'd' ,
- .BR 'l' ,
- .BR 'p' ,
- .BR 'f' ,
- or
- .BR 's'
- for block special file, character special file, directory, symbolic
- link, FIFO, regular file, or socket, respectively.
- .IP "\fB\-links\ \fIn\fR" 10
- The primary shall evaluate as true if the file has
- .IR n
- links.
- .IP "\fB\-user\ \fIuname\fR" 10
- The primary shall evaluate as true if the file belongs to the user
- .IR uname.
- If
- .IR uname
- is a decimal integer and the
- \fIgetpwnam\fR()
- (or equivalent) function does not return a valid user name,
- .IR uname
- shall be interpreted as a user ID.
- .IP "\fB\-group\ \fIgname\fR" 10
- .br
- The primary shall evaluate as true if the file belongs to the group
- .IR gname .
- If
- .IR gname
- is a decimal integer and the
- \fIgetgrnam\fR()
- (or equivalent) function does not return a valid group name,
- .IR gname
- shall be interpreted as a group ID.
- .IP "\fB\-size\ \fIn\fB[c]\fR" 10
- The primary shall evaluate as true if the file size in bytes, divided
- by 512 and rounded up to the next integer, is
- .IR n .
- If
- .IR n
- is followed by the character
- .BR 'c' ,
- the size shall be in bytes.
- .IP "\fB\-atime\ \fIn\fR" 10
- The primary shall evaluate as true if the file access time subtracted
- from the initialization time, divided by 86\|400 (with any remainder
- discarded), is
- .IR n .
- .IP "\fB\-ctime\ \fIn\fR" 10
- The primary shall evaluate as true if the time of last change of file
- status information subtracted from the initialization time, divided by
- 86\|400 (with any remainder discarded), is
- .IR n .
- .IP "\fB\-mtime\ \fIn\fR" 10
- The primary shall evaluate as true if the file modification time
- subtracted from the initialization time, divided by 86\|400 (with any
- remainder discarded), is
- .IR n .
- .IP "\fB\-exec\ \fIutility_name\ \fB[\fIargument\fR\ .\|.\|.\fB]\ ;\fR" 10
- .IP "\fB\-exec\ \fIutility_name\ \fB[\fIargument\fR\ .\|.\|.\fB]\ \ \fR{\|}\0+" 10
- .br
- The end of the primary expression shall be punctuated by a
- <semicolon>
- or by a
- <plus-sign>.
- Only a
- <plus-sign>
- that immediately follows an argument containing only the two characters
- .BR \(dq{}\(dq
- shall punctuate the end of the primary expression. Other uses of the
- <plus-sign>
- shall not be treated as special.
- .RS 10
- .P
- If the primary expression is punctuated by a
- <semicolon>,
- the utility
- .IR 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 status. A
- .IR utility_name
- or
- .IR argument
- containing only the two characters
- .BR \(dq{}\(dq
- shall be replaced by the current pathname. If a
- .IR utility_name
- or
- .IR argument
- string contains the two characters
- .BR \(dq{}\(dq ,
- but not just the two characters
- .BR \(dq{}\(dq ,
- it is implementation-defined whether
- .IR find
- replaces those two characters or uses the string without change.
- .P
- 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
- .IR utility_name
- shall be invoked once for each set of aggregated pathnames. Each
- invocation shall begin after the last pathname in the set is
- aggregated, and shall be completed before the
- .IR 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
- .IR find
- utility shall return a non-zero exit status. An argument containing
- only the two characters
- .BR \(dq{}\(dq
- 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 the two
- characters
- .BR \(dq{}\(dq
- is present, the behavior is unspecified.
- .P
- The current directory for the invocation of
- .IR utility_name
- shall be the same as the current directory when the
- .IR find
- utility was started. If the
- .IR utility_name
- names any of the special built-in utilities (see
- .IR "Section 2.14" ", " "Special Built-In Utilities"),
- the results are undefined.
- .RE
- .IP "\fB\-ok\ \fIutility_name\ \fB[\fIargument\fR\ .\|.\|.\fB]\ ;\fR" 10
- .br
- The
- .BR \-ok
- primary shall be equivalent to
- .BR \-exec ,
- except that the use of a
- <plus-sign>
- to punctuate the end of the primary expression need not be supported, and
- .IR find
- shall request affirmation of the invocation of
- .IR 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
- .BR \-ok
- operand shall be false.
- .IP "\fB\-print\fR" 10
- The primary shall always evaluate as true; it shall cause the current
- pathname to be written to standard output.
- .IP "\fB\-newer\ \fIfile\fR" 10
- 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
- .IR file .
- .IP "\fB\-depth\fR" 10
- 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
- .BR \-depth
- primary is not specified, all entries in a directory shall be acted on
- after the directory itself. If any
- .BR \-depth
- primary is specified, it shall apply to the entire expression even if
- the
- .BR \-depth
- primary would not normally be evaluated.
- .P
- The primaries can be combined using the following operators (in order
- of decreasing precedence):
- .IP "(\ \fIexpression\fR\ )" 10
- True if
- .IR expression
- is true.
- .IP "\fB!\ \fIexpression\fR" 10
- Negation of a primary; the unary NOT operator.
- .IP "\fIexpression\ \fB[\-a]\ \fIexpression\fR" 10
- .br
- Conjunction of primaries; the AND operator is implied by the
- juxtaposition of two primaries or made explicit by the optional
- .BR \-a
- operator. The second expression shall not be evaluated if the first
- expression is false.
- .IP "\fIexpression\ \fB\-o\ \fIexpression\fR" 10
- .br
- Alternation of primaries; the OR operator. The second expression shall
- not be evaluated if the first expression is true.
- .P
- If no
- .IR expression
- is present,
- .BR \-print
- shall be used as the expression. Otherwise, if the given expression
- does not contain any of the primaries
- .BR \-exec ,
- .BR \-ok ,
- or
- .BR \-print ,
- the given expression shall be effectively replaced by:
- .sp
- .RS 4
- .nf
- ( \fIgiven_expression\fP ) -print
- .fi
- .P
- .RE
- .P
- The
- .BR \-user ,
- .BR \-group ,
- and
- .BR \-newer
- primaries each shall evaluate their respective arguments only once.
- .P
- When the file type evaluated for the current file is a symbolic link,
- the results of evaluating the
- .BR \-perm
- primary are implementation-defined.
- .SH STDIN
- If the
- .BR \-ok
- primary is used, the response shall be read from the standard input.
- An entire line shall be read as the response. Otherwise, the standard
- input shall not be used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR find :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_COLLATE\fP" 10
- .br
- Determine the locale for the behavior of ranges, equivalence classes,
- and multi-character collating elements used in the pattern matching
- notation for the
- .BR \-n
- option and in the extended regular expression defined for the
- .BR yesexpr
- locale keyword in the
- .IR LC_MESSAGES
- category.
- .IP "\fILC_CTYPE\fP" 10
- This variable determines the locale for the interpretation of sequences
- of bytes of text data as characters (for example, single-byte
- as opposed to multi-byte characters in arguments), the behavior of
- character classes within the pattern matching notation used for the
- .BR \-n
- option, and the behavior of character classes within regular
- expressions used in the extended regular expression defined for the
- .BR yesexpr
- locale keyword in the
- .IR LC_MESSAGES
- category.
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale used to process affirmative responses, and the
- locale used to affect the format and contents of diagnostic messages
- and prompts written to standard error.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .IP "\fIPATH\fP" 10
- Determine the location of the
- .IR utility_name
- for the
- .BR \-exec
- and
- .BR \-ok
- primaries, as described in the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables".
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- The
- .BR \-print
- primary shall cause the current pathnames to be written to standard
- output. The format shall be:
- .sp
- .RS 4
- .nf
- "%s\en", <\fIpath\fR>
- .fi
- .P
- .RE
- .SH STDERR
- The
- .BR \-ok
- primary shall write a prompt to standard error containing at least the
- .IR utility_name
- to be invoked and the current pathname. In the POSIX locale, the last
- non-\c
- <blank>
- in the prompt shall be
- .BR '?' .
- The exact format used is unspecified.
- .P
- Otherwise, the standard error shall be used only for diagnostic
- messages.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- All
- .IR path
- operands were traversed successfully.
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- When used in operands, pattern matching notation,
- <semicolon>,
- <left-parenthesis>,
- and
- <right-parenthesis>
- characters are special to the shell and must be quoted (see
- .IR "Section 2.2" ", " "Quoting").
- .P
- The bit that is traditionally used for sticky (historically 01000) is
- specified in the
- .BR \-perm
- primary using the octal number argument form. Since this bit is not
- defined by this volume of POSIX.1\(hy2017, applications must not assume that it actually refers
- to the traditional sticky bit.
- .SH EXAMPLES
- .IP " 1." 4
- The following commands are equivalent:
- .RS 4
- .sp
- .RS 4
- .nf
- find .
- find . -print
- .fi
- .P
- .RE
- .P
- They both write out the entire directory hierarchy from the current
- directory.
- .RE
- .IP " 2." 4
- The following command:
- .RS 4
- .sp
- .RS 4
- .nf
- find / \e( -name tmp -o -name \(aq*.xx\(aq \e) -atime +7 -exec rm {} \e;
- .fi
- .P
- .RE
- .P
- removes all files named
- .BR tmp
- or ending in
- .BR .xx
- that have not been accessed for seven or more 24-hour periods.
- .RE
- .IP " 3." 4
- The following command:
- .RS 4
- .sp
- .RS 4
- .nf
- find . -perm -o+w,+s
- .fi
- .P
- .RE
- .P
- prints (\c
- .BR \-print
- is assumed) the names of all files in or below the current directory,
- with all of the file permission bits S_ISUID, S_ISGID, and S_IWOTH set.
- .RE
- .IP " 4." 4
- The following command:
- .RS 4
- .sp
- .RS 4
- .nf
- find . -name SCCS -prune -o -print
- .fi
- .P
- .RE
- .P
- recursively prints pathnames of all files in the current directory and
- below, but skips directories named SCCS and files in them.
- .RE
- .IP " 5." 4
- The following command:
- .RS 4
- .sp
- .RS 4
- .nf
- find . -print -name SCCS -prune
- .fi
- .P
- .RE
- .P
- behaves as in the previous example, but prints the names of the SCCS
- directories.
- .RE
- .IP " 6." 4
- The following command is roughly equivalent to the
- .BR \-nt
- extension to
- .IR test :
- .RS 4
- .sp
- .RS 4
- .nf
- if [ -n "$(find file1 -prune -newer file2)" ]; then
- printf %s\e\en "file1 is newer than file2"
- fi
- .fi
- .P
- .RE
- .RE
- .IP " 7." 4
- The descriptions of
- .BR \-atime ,
- .BR \-ctime ,
- and
- .BR \-mtime
- use the terminology
- .IR n
- ``86\|400 second periods (days)''. For example, a file accessed at 23:59
- is selected by:
- .RS 4
- .sp
- .RS 4
- .nf
- find . -atime -1 -print
- .fi
- .P
- .RE
- .P
- 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.
- .RE
- .IP " 8." 4
- The following command:
- .RS 4
- .sp
- .RS 4
- .nf
- find . ! -name . -prune -name \(aq*.old\(aq -exec \e
- sh -c \(aqmv "$@" ../old/\(aq sh {} +
- .fi
- .P
- .RE
- .P
- performs the same task as:
- .sp
- .RS 4
- .nf
- mv ./*.old ./.old ./.*.old ../old/
- .fi
- .P
- .RE
- .P
- while avoiding an ``Argument list too long'' error if there are
- a large number of files ending with
- .BR .old
- and without running
- .IR mv
- if there are no such files (and avoiding ``No such file or directory''
- errors if
- .BR ./.old
- does not exist or no files match
- .BR ./*.old
- or
- .BR ./.*.old ).
- .P
- The alternative:
- .sp
- .RS 4
- .nf
- find . ! -name . -prune -name \(aq*.old\(aq -exec mv {} ../old/ \e;
- .fi
- .P
- .RE
- .P
- is less efficient if there are many files to move because it executes one
- .IR mv
- command per file.
- .RE
- .IP " 9." 4
- On systems configured to mount removable media on directories under
- .BR /media ,
- the following command searches the file hierarchy for files larger
- than 100\|000 KB without searching any mounted removable media:
- .RS 4
- .sp
- .RS 4
- .nf
- find / -path /media -prune -o -size +200000 -print
- .fi
- .P
- .RE
- .RE
- .IP 10. 4
- Except for the root directory, and
- .BR \(dq//\(dq
- on implementations where
- .BR \(dq//\(dq
- does not refer to the root directory, no pattern given to
- .BR \-name
- will match a
- <slash>,
- because trailing
- <slash>
- characters are ignored when computing the basename of the file under
- evaluation. Given two empty directories named
- .BR foo
- and
- .BR bar ,
- the following command:
- .RS 4
- .sp
- .RS 4
- .nf
- find foo/// bar/// -name foo -o -name \(aqbar?*\(aq
- .fi
- .P
- .RE
- .P
- prints only the line
- .BR \(dqfoo///\(dq .
- .RE
- .SH RATIONALE
- The
- .BR \-a
- operator was retained as an optional operator for compatibility with
- historical shell scripts, even though it is redundant with expression
- concatenation.
- .P
- The descriptions of the
- .BR '\-'
- modifier on the
- .IR mode
- and
- .IR onum
- arguments to the
- .BR \-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
- having exactly the matching bits set.
- .P
- The exact format of the interactive prompts is unspecified. Only the
- general nature of the contents of prompts are specified because:
- .IP " *" 4
- Implementations may desire more descriptive prompts than those
- used on historical implementations.
- .IP " *" 4
- Since the historical prompt strings do not terminate with
- <newline>
- characters, there is no portable way for another program to interact
- with the prompts of this utility via pipes.
- .P
- 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.
- .P
- The
- .BR \-name
- .IR file
- operand was changed to use the shell pattern matching notation
- so that
- .IR find
- is consistent with other utilities using pattern matching.
- .P
- The
- .BR \-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
- .IR st_size
- field defined in the System Interfaces volume of POSIX.1\(hy2017 should be used, not the
- .IR st_blocks
- found in historical implementations. There are at least two reasons for
- this:
- .IP " 1." 4
- In both System V and BSD,
- .IR find
- only uses
- .IR st_size
- in size calculations for the operands specified by this volume of POSIX.1\(hy2017. (BSD uses
- .IR st_blocks
- only when processing the
- .BR \-ls
- primary.)
- .IP " 2." 4
- Users usually think of file size in terms of bytes, which is also the
- unit used by the
- .IR ls
- utility for the output from the
- .BR \-l
- option. (In both System V and BSD,
- .IR ls
- uses
- .IR st_size
- for the
- .BR \-l
- option size field and uses
- .IR st_blocks
- for the
- .IR ls
- .BR \-s
- calculations. This volume of POSIX.1\(hy2017 does not specify
- .IR ls
- .BR \-s .)
- .P
- The descriptions of
- .BR \-atime ,
- .BR \-ctime ,
- and
- .BR \-mtime
- were changed from the SVID description of
- .IR n
- ``days'' to
- .IR n
- being the result of the integer division of the time difference in
- seconds by 86\|400. The description is also different in terms of the
- exact timeframe for the
- .IR n
- case (\fIversus\fP the
- .IR +n
- or
- .IR \-n ),
- but it matches all known historical implementations. It refers to one
- 86\|400 second period in the past, not any time from the beginning of
- that period to the current time. For example,
- .BR \-atime
- 2 is true if the file was accessed any time in the period from 72 hours
- to 48 hours ago.
- .P
- Historical implementations do not modify
- .BR \(dq{}\(dq
- when it appears as a substring of an
- .BR \-exec
- or
- .BR \-ok
- .IR utility_name
- or argument string. There have been numerous user requests for this
- extension, so this volume of POSIX.1\(hy2017 allows the desired behavior. At least one recent
- implementation does support this feature, but encountered several
- problems in managing memory allocation and dealing with multiple
- occurrences of
- .BR \(dq{}\(dq
- in a string while it was being developed, so it is not yet required
- behavior.
- .P
- Assuming the presence of
- .BR \-print
- was added to correct a historical pitfall that plagues novice users, it
- is entirely upwards-compatible from the historical System V
- .IR find
- utility. In its simplest form (\c
- .IR find
- .IR directory ),
- it could be confused with the historical BSD fast
- .IR find .
- The BSD developers agreed that adding
- .BR \-print
- as a default expression was the correct decision and have added the
- fast
- .IR find
- functionality within a new utility called
- .IR locate .
- .P
- Historically, the
- .BR \-L
- option was implemented using the primary
- .BR \-follow .
- The
- .BR \-H
- and
- .BR \-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
- .BR \-follow
- primary always evaluated to true. As they were historically really
- global variables that took effect before the traversal began, some
- valid expressions had unexpected results. An example is the expression
- .BR \-print
- .BR \-o
- .BR \-follow .
- Because
- .BR \-print
- always evaluates to true, the standard order of evaluation implies that
- .BR \-follow
- would never be evaluated. This was never the case. Historical practice
- for the
- .BR \-follow
- primary, however, is not consistent. Some implementations always follow
- symbolic links on the command line whether
- .BR \-follow
- is specified or not. Others follow symbolic links on the command line
- only if
- .BR \-follow
- is specified. Both behaviors are provided by the
- .BR \-H
- and
- .BR \-L
- options, but scripts using the current
- .BR \-follow
- primary would be broken if the
- .BR \-follow
- option is specified to work either way.
- .P
- Since the
- .BR \-L
- option resolves all symbolic links and the
- .BR \-type
- .IR l
- primary is true for symbolic links that still exist after symbolic
- links have been resolved, the command:
- .sp
- .RS 4
- .nf
- find -L . -type l
- .fi
- .P
- .RE
- .P
- prints a list of symbolic links reachable from the current directory
- that do not resolve to accessible files.
- .P
- A feature of SVR4's
- .IR find
- utility was the
- .BR \-exec
- primary's
- .BR +
- terminator. This allowed filenames containing special characters
- (especially
- <newline>
- characters) to be grouped together without the problems that occur if
- such filenames are piped to
- .IR xargs .
- Other implementations have added other ways to get around this problem,
- notably a
- .BR \-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
- .IR find 's
- .BR \-print0
- output had to add a new option to parse the null terminators it would
- now be reading.
- .P
- The
- .BR \(dq-exec ... {} +\(dq
- syntax adopted was a result of IEEE PASC Interpretation 1003.2 #210. It
- should be noted that this is an incompatible change to IEEE\ Std 1003.2\(hy1992. For example,
- the following command printed all files with a
- .BR '\-'
- after their name if they are regular files, and a
- .BR '\(pl'
- otherwise:
- .sp
- .RS 4
- .nf
- find / -type f -exec echo {} - \(aq;\(aq -o -exec echo {} + \(aq;\(aq
- .fi
- .P
- .RE
- .P
- The change invalidates usage like this. Even though the previous
- standard stated that this usage would work, in practice many did not
- support it and the standard developers felt it better to now state that
- this was not allowable.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Section 2.2" ", " "Quoting",
- .IR "Section 2.13" ", " "Pattern Matching Notation",
- .IR "Section 2.14" ", " "Special Built-In Utilities",
- .IR "\fIchmod\fR\^",
- .IR "\fImv\fR\^",
- .IR "\fIpax\fR\^",
- .IR "\fIsh\fR\^",
- .IR "\fItest\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .P
- The System Interfaces volume of POSIX.1\(hy2017,
- .IR "\fIfstatat\fR\^(\|)",
- .IR "\fIgetgrgid\fR\^(\|)",
- .IR "\fIgetpwuid\fR\^(\|)"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .