[src/trunk]: src/usr.bin/find Updates to the find(1) man page, based on PR 45...

[apb <apb%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/5ba446658603
branches:  trunk
changeset: 769816:5ba446658603
user:      apb <apb%NetBSD.org@localhost>
date:      Sat Sep 24 13:45:43 2011 +0000

description:
Updates to the find(1) man page, based on PR 45381 from Greg Woods,
with additional changes by myself.

diffstat:

 usr.bin/find/find.1 |  231 +++++++++++++++++++++++++++++++--------------------
 1 files changed, 141 insertions(+), 90 deletions(-)

diffs (truncated from 397 to 300 lines):

diff -r 04566835c860 -r 5ba446658603 usr.bin/find/find.1
--- a/usr.bin/find/find.1       Sat Sep 24 12:02:58 2011 +0000
+++ b/usr.bin/find/find.1       Sat Sep 24 13:45:43 2011 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: find.1,v 1.70 2010/09/09 11:42:13 wiz Exp $
+.\"    $NetBSD: find.1,v 1.71 2011/09/24 13:45:43 apb Exp $
 .\"
 .\" Copyright (c) 1990, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -32,7 +32,7 @@
 .\"
 .\"    from: @(#)find.1        8.7 (Berkeley) 5/9/95
 .\"
-.Dd November 6, 2009
+.Dd September 24, 2011
 .Dt FIND 1
 .Os
 .Sh NAME
@@ -179,6 +179,18 @@
 Does not list mount points to other file systems.
 .El
 .Sh PRIMARIES
+All primaries which take a numeric argument of
+.Ar n
+allow the number to be preceded by a plus sign
+.Pq Dq \&+
+or a minus sign
+.Pq Dq \- .
+A preceding plus sign means
+.Dq more than Ar n ,
+a preceding minus sign means
+.Dq less than Ar n ,
+and neither means
+.Dq exactly Ar n .
 .Bl -tag -width Ds -compact
 .It Ic -amin Ar n
 True if the difference between the file last access time and the time
@@ -237,77 +249,106 @@
 .It Ic -empty
 True if the current file or directory is empty.
 .Pp
-.It Ic -exec Ar utility Oo argument ... Oc No ;
-.It Ic -exec Ar utility Oo argument ... Oc No {} +
+.It Ic -exec Ar utility Oo argument ... Oc Ic \&;
+.It Ic -exec Ar utility Oo argument ... Oc Ic {} Ic \&+
 Execute the specified
 .Ar utility
 with the specified arguments.
-The list of arguments is terminated by
-.Dq Li \&;
-or
-.Dq Li \&+ .
+.Pp
+The list of arguments for
 .Ar utility
-will be executed from the directory from which
+is terminated by a lone semicolon
+.Dq Ic \&;
+or plus
+.Dq Ic \&+
+character as a separate parameter.
+The command specified by
+.Ar utility
+will be executed with its current working directory being the directory
+from which
 .Nm
 was executed.
 .Pp
-If terminated by a semicolon
-.Pq Dq \&; ,
-the
+If the list of arguments is terminated by a semicolon
+.Pq Dq Ic \&; ,
+then the
 .Ar utility
-is invoked once per path.
-If the string
-.Dq {}
-appears anywhere in the utility name or the arguments,
-it is replaced by the pathname of the current file.
+is invoked once per pathname.
+If
+the string
+.Dq Ic {}
+appears anywhere in the utility name or the arguments
+then it is replaced by the pathname of the current file
+(but it need not appear, in which case the pathname
+will not be passed to the
+.Ar utility ) .
+The semicolon-terminated form of the
+.Ic -exec
+primary returns true if and only if the
+.Ar utility
+exits with a zero exit status.
+Note that the semicolon will have to be escaped on the shell command line
+in order to be passed as a parameter.
 .Pp
-If terminated by a plus sign
-.Pq Dq \&+ ,
-the pathnames for which the
-primary is evaluated are aggregated into sets, and
+If the list of arguments is terminated by a plus sign
+.Pq Dq Ic \&+ ,
+then the pathnames for which the primary is evaluated are aggregated
+into sets, and
 .Ar utility
 will be invoked once per set, similar to
 .Xr xargs 1 .
-If any invocation exits with non-zero exit status, then
+In this case the parameter
+.Dq Ic {}
+must appear as the last item in the argument list, just before the
+.Dq Ic \&+
+parameter.
+Each set is limited to no more than 5,000 pathnames,
+and is also limited such that the total number of bytes in the argument
+list does not exceed
+.Dv ARG_MAX .
+The plus-terminated form of the
+.Ic -exec
+primary always returns true.
+If the plus-terminated form of the
+.Ic -exec
+primary results in any invocation of the
+.Ar utility
+exiting with non-zero exit status, then
 .Nm
-will eventually do so as well, but this does not cause
+will eventually exit with non-zero status as well,
+but this does not cause
 .Nm
 to exit early.
-The string
-.Dq {}
-must appear, and must appear last.
-Each set is limited to no more than 5,000 pathnames,
-and is also limited such that the invocation of
-.Ar utility
-does not exceed
-.Dv ARG_MAX .
 .Pp
-.It Ic -execdir Ar utility Oo argument ... Oc No ;
+.It Ic -execdir Ar utility Oo argument ... Oc Ic \&;
 The
 .Ic -execdir
 primary is similar to the semicolon-terminated
-.Pq Dq \&;
+.Pq Dq Ic \&;
 variant of the
 .Ic -exec
 primary, with the exception that
 .Ar utility
 will be executed from the directory that holds
 the current file.
-The filename substituted for the string
-.Dq {}
-is not qualified.
+Only the base filename is substituted for the string
+.Dq Ic {} .
 Set aggregation
-.Pq Do \&+ Dc termination
+.Pq Do Ic \&+ Dc termination
 is not supported.
 .Pp
-.It Ic -exit Op Ar n
+.It Ic -exit Op Ar status
 This primary causes
 .Nm
-to stop traversing the file system and exit immediately if a
-previous condition was met.
-If no value is specified, the exit value will be 0, else
-.Ar n .
-Note that other primaries will be evaluated and acted upon before exiting.
+to stop traversing the file system and exit immediately,
+with the specified numeric exit status.
+If the
+.Ar status
+value is not specified, then
+.Nm
+will exit with status zero.
+Note that any preceding primaries will be evaluated and acted upon
+before exiting.
 .Pp
 .It Ic -false
 This primary always evaluates to false.
@@ -323,7 +364,7 @@
 If
 .Ar flags
 are preceded by a dash
-.Pq Dq - ,
+.Pq Dq Ic \- ,
 this primary evaluates to true
 if at least all of the bits in
 .Ar flags
@@ -448,7 +489,7 @@
 .Ar n
 24-hour periods.
 .Pp
-.It Ic -ok Ar utility Oo argument ... Oc No ;
+.It Ic -ok Ar utility Oo argument ... Oc Ic ;
 The
 .Ic -ok
 primary is similar to the semicolon-terminated
@@ -462,7 +503,7 @@
 If the response is other than
 .Dq y ,
 the command is not executed and the
-.Ar -ok
+.Ic -ok
 primary evaluates to false.
 Set aggregation
 .Pq Do \&+ Dc termination
@@ -539,13 +580,13 @@
 of the file's mode bits participate
 in the comparison.
 If the mode is preceded by a dash
-.Pq Dq - ,
+.Pq Dq Ic \- ,
 this primary evaluates to true
 if at least all of the bits in the mode are set in the file's mode bits.
 If the mode is not preceded by a dash, this primary evaluates to true if
 the bits in the mode exactly match the file's mode bits.
 Note, the first character of a symbolic mode may not be a dash
-.Pq Dq - .
+.Pq Dq Ic \- .
 .Pp
 .It Ic -print
 This primary always evaluates to true.
@@ -567,7 +608,7 @@
 .It Ic -print0
 This primary always evaluates to true.
 It prints the pathname of the current file to standard output, followed
-by a null character.
+by a NUL character.
 .Pp
 .It Ic -printx
 This primary always evaluates to true.
@@ -603,7 +644,7 @@
 If
 .Ar n
 is followed by a
-.Dq c ,
+.Dq Ic c ,
 then the primary is true if the file's size is
 .Ar n
 bytes.
@@ -649,18 +690,6 @@
 .Xr stat 2
 S5.6.2 [POSIX.1]).
 .El
-.Pp
-All primaries which take a numeric argument allow the number to be
-preceded by a plus sign
-.Pq Dq +
-or a minus sign
-.Pq Dq \- .
-A preceding plus sign means
-.Dq more than n ,
-a preceding minus sign means
-.Dq less than n ,
-and neither means
-.Dq exactly n .
 .Sh OPERATORS
 The primaries may be combined using the following operators.
 The operators are listed in order of decreasing precedence.
@@ -709,39 +738,51 @@
 utility normally exits 0 on success, and exits with 1 under certain
 internal error conditions.
 If any invocations of
-.Dq Ic -exec Ar ... No +
+.Dq Ic -exec Ar ... Ic \&+
 primaries return non-zero exit-status, then
 .Nm
 will do so as well.
 .Sh EXAMPLES
 The following examples are shown as given to the shell:
 .Bl -tag -width findx
-.It Li "find  /  \e!  -name  \*q*.c\*q  -print"
+.It Li "find  /  \e!  -name  \*q*.c\*q  \-print"
 Print out a list of all the files whose names do not end in
 .Dq \&.c .
-.It Li "find  /  -newer  ttt  -user  wnj  -print"
+.It Li "find  /  \-newer  ttt  \-user  wnj  \-print"
 Print out a list of all the files owned by user
 .Dq wnj
 that are newer than the file
 .Dq ttt .
-.It Li "find  /  \e!  \e(  -newer  ttt  -user  wnj  \e)  -print"
+.It Li "find  .  \-type  f  \-mmin  \-30  \-print  \-or  \-mindepth  1  \-prune"
+Print out a list of all the files in the current directory that are
+newer than 30 minutes.
+.It Li "find  .  \-type  f  \-atime  +10  \-mindepth  2  \-print"
+Print out a list of all the files in any sub-directories that have not
+been accessed in the past ten days.
+.It Li "find  .  \-mtime  +90  \-exec  rm  \-i  {}  +  \-or  \-mindepth  1  \-prune"
+Interactively remove all of the files in the current directory that have
+not been modified in 90 days.
+.It Li "find  .  \-type  f  \-mtime  +90  \-ok  mv  {}  {}.old  \e;"
+Interactively rename all of the files in the current directory and all
+sub-directories that have not been modified in 90 days.