diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/find.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/find.1p | 1132 |
1 files changed, 1132 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/find.1p b/man-pages-posix-2017/man1p/find.1p new file mode 100644 index 0000000..c46d4ab --- /dev/null +++ b/man-pages-posix-2017/man1p/find.1p @@ -0,0 +1,1132 @@ +'\" 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 . |