find.html

IEEE 1003.1-2003, Single Unix Specification v3

<pre>
<tt>find . -perm -o+w,+s
</tt>
</pre>

<p>prints ( <b>-print</b> 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.</p>
</li>

<li>
<p>The following command:</p>

<pre>
<tt>find . -name SCCS -prune -o -print
</tt>
</pre>

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

<li>
<p>The following command:</p>

<pre>
<tt>find . -print -name SCCS -prune
</tt>
</pre>

<p>behaves as in the previous example, but prints the names of the SCCS directories.</p>
</li>

<li>
<p>The following command is roughly equivalent to the <b>-nt</b> extension to <a href="../utilities/test.html"><i>test</i></a>:</p>

<pre>
<tt>if [ -n "$(find file1 -prune -newer file2)" ]; then
    printf %s\\n "file1 is newer than file2"
fi
</tt>
</pre>
</li>

<li>
<p>The descriptions of <b>-atime</b>, <b>-ctime</b>, and <b>-mtime</b> use the terminology <i>n</i> &quot;86400 second periods
(days)&quot;. For example, a file accessed at 23:59 is selected by:</p>

<pre>
<tt>find . -atime -1 -print
</tt>
</pre>

<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.</p>
</li>
</ol>
</blockquote>

<h4><a name="tag_04_55_18"></a>RATIONALE</h4>

<blockquote>
<p>The <b>-a</b> operator was retained as an optional operator for compatibility with historical shell scripts, even though it is
redundant with expression concatenation.</p>

<p>The descriptions of the <tt>'-'</tt> modifier on the <i>mode</i> and <i>onum</i> arguments to the <b>-perm</b> 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>

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

<ul>
<li>
<p>Implementations may desire more descriptive prompts than those used on historical implementations.</p>
</li>

<li>
<p>Since the historical prompt strings do not terminate with &lt;newline&gt;s, there is no portable way for another program to
interact with the prompts of this utility via pipes.</p>
</li>
</ul>

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

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

<p>The <b>-size</b> 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 <i>st_size</i> field defined in the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001 should be used,
not the <i>st_blocks</i> found in historical implementations. There are at least two reasons for this:</p>

<ol>
<li>
<p>In both System V and BSD, <i>find</i> only uses <i>st_size</i> in size calculations for the operands specified by this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001. (BSD uses <i>st_blocks</i> only when processing the <b>-ls</b> primary.)</p>
</li>

<li>
<p>Users usually think of file size in terms of bytes, which is also the unit used by the <a href=
"../utilities/ls.html"><i>ls</i></a> utility for the output from the <b>-l</b> option. (In both System V and BSD, <a href=
"../utilities/ls.html"><i>ls</i></a> uses <i>st_size</i> for the <b>-l</b> option size field and uses <i>st_blocks</i> for the <a
href="../utilities/ls.html"><i>ls</i></a> <b>-s</b> calculations. This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 does not specify <a
href="../utilities/ls.html"><i>ls</i></a> <b>-s</b>.)</p>
</li>
</ol>

<p>The descriptions of <b>-atime</b>, <b>-ctime</b>, and <b>-mtime</b> were changed from the SVID description of <i>n</i> &quot;days''
to &quot;24-hour periods&quot;. The description is also different in terms of the exact timeframe for the <i>n</i> case (<i>versus</i> the
<i>+n</i> or <i>-n</i>), 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, <b>-atime</b> 3 is true if the file was accessed any
time in the period from 72 hours to 48 hours ago.</p>

<p>Historical implementations do not modify <tt>"{}"</tt> when it appears as a substring of an <b>-exec</b> or <b>-ok</b>
<i>utility_name</i> or argument string. There have been numerous user requests for this extension, so this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001 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 <tt>"{}"</tt> in a string while
it was being developed, so it is not yet required behavior.</p>

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

<p>Historically, the <b>-L</b> option was implemented using the primary <b>-follow</b>. The <b>-H</b> and <b>-L</b> 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 <b>-follow</b> 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 <b>-print</b>
<b>-o</b> <b>-follow</b>. Because <b>-print</b> always evaluates to true, the standard order of evaluation implies that
<b>-follow</b> would never be evaluated. This was never the case. Historical practice for the <b>-follow</b> primary, however, is
not consistent. Some implementations always follow symbolic links on the command line whether <b>-follow</b> is specified or not.
Others follow symbolic links on the command line only if <b>-follow</b> is specified. Both behaviors are provided by the <b>-H</b>
and <b>-L</b> options, but scripts using the current <b>-follow</b> primary would be broken if the <b>-follow</b> option is
specified to work either way.</p>

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

<pre>
<tt>find -L . -type l
</tt>
</pre>

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

<p>A feature of SVR4's <i>find</i> utility was the <b>-exec</b> primary's <b>+</b> terminator. This allowed filenames containing
special characters (especially &lt;newline&gt;s) to be grouped together without the problems that occur if such filenames are piped
to <a href="../utilities/xargs.html"><i>xargs</i></a>. Other implementations have added other ways to get around this problem,
notably a <b>-print0</b> 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 <i>find</i>'s <b>-print0</b> output had to add a new option to
parse the null terminators it would now be reading.</p>

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

<pre>
<tt>find / -type f -exec echo {} - ';' -o -exec echo {} + ';'
</tt>
</pre>

<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.</p>
</blockquote>

<h4><a name="tag_04_55_19"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_55_20"></a>SEE ALSO</h4>

<blockquote>
<p><a href="xcu_chap02.html#tag_02_02"><i>Quoting</i></a> , <a href="xcu_chap02.html#tag_02_13"><i>Pattern Matching
Notation</i></a> , <a href="xcu_chap02.html#tag_02_14"><i>Special Built-In Utilities</i></a> , <a href=
"chmod.html"><i>chmod</i>()</a> , <a href="pax.html"><i>pax</i></a> , <a href="sh.html"><i>sh</i></a> , <a href=
"test.html"><i>test</i></a> , the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../functions/getgrgid.html"><i>getgrgid</i>()</a>, <a href="../functions/getpwuid.html"><i>getpwuid</i>()</a>, <a href=
"../functions/stat.html"><i>stat</i>()</a></p>
</blockquote>

<h4><a name="tag_04_55_21"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 2.</p>
</blockquote>

<h4><a name="tag_04_55_22"></a>Issue 5</h4>

<blockquote>
<p>The FUTURE DIRECTIONS section is added.</p>
</blockquote>

<h4><a name="tag_04_55_23"></a>Issue 6</h4>

<blockquote>
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>

<ul>
<li>
<p>The <b>-perm&nbsp;[-]</b><i>onum</i> primary is supported.</p>
</li>
</ul>

<p>The <i>find</i> utility is aligned with the IEEE&nbsp;P1003.2b draft standard, to include processing of symbolic links and
changes to the description of the <b>atime</b>, <b>ctime</b>, and <b>mtime</b> operands.</p>

<p>IEEE PASC Interpretation 1003.2 #210 is applied, extending the <b>-exec</b> operand.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>