BSD 4_4_Lite2 release

[unix-history] / usr / src / usr.bin / find / find.1

diff --git a/usr/src/usr.bin/find/find.1 b/usr/src/usr.bin/find/find.1
index 2b2a7f7..a5fc173 100644 (file)
--- a/usr/src/usr.bin/find/find.1
+++ b/usr/src/usr.bin/find/find.1
@@ -1,266 +1,461 @@
-.\" Copyright (c) 1985 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1990, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\"    @(#)find.1      6.3 (Berkeley) %G%
+.\" This code is derived from software contributed to Berkeley by
+.\" the Institute of Electrical and Electronics Engineers, Inc.

 .\"
 .\"

-.TH FIND 1 ""
-.AT 3
-.SH NAME
-find \- find files
-.SH SYNOPSIS
-.B find
-pathname-list expression
-.br 
-.B find
-pattern
-.SH DESCRIPTION
-In the first form above,
-.I find
-recursively descends
-the directory hierarchy for
-each pathname in the
-.I pathname-list
-(i.e., one or more pathnames)
-seeking files that match a boolean
-.I expression
-written in the primaries given below.
-In the descriptions, the argument
-.I n
-is used as a decimal integer
-where
-.I +n
-means more than
-.I n,
-.I \-n
-means less than
-.I n
-and
-.I n
-means exactly
-.IR n .
-.PP
-The second form rapidly searches a database for all pathnames
-which match
-.IR pattern .
-Usually the database is recomputed
-weekly and contains the pathnames
-of all files which are publicly accessible.
-If escaped, normal shell
-\*(lqglobbing\*(rq characters (`*', `?', `[', and ']')
-may be used in
-.IR pattern ,
-but the matching differs in that no characters
-.RI ( e.g. " `/')"
-have to be matched explicitly.
-As a special case, a simple
-.I pattern
-containing no globbing characters
-is matched as though it were
-.IR *pattern* ;
-if any globbing character appears
-there are no implicit globbing characters.
-.TP 10n
-.BR \-name " filename"
-True if the
-.I filename
-argument matches the current file name.
-Normal
-shell
-argument syntax may be used if escaped (watch out for
-`[', `?' and `*').
-.TP
-.BR \-perm " onum"
-True if the file permission flags
-exactly
-match the
-octal number
-.I onum
-(see
-.IR  chmod (1)).
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"    @(#)find.1      8.7 (Berkeley) 5/9/95
+.\"
+.Dd May 9, 1995
+.Dt FIND 1
+.Os
+.Sh NAME
+.Nm find
+.Nd walk a file hierarchy
+.Sh SYNOPSIS
+.Nm find
+.Op Fl H | Fl L | Fl P
+.Op Fl Xdx
+.Op Fl f Ar file
+.Op Ar file ...
+.Ar expression
+.Sh DESCRIPTION
+.Nm Find
+recursively descends the directory tree for each
+.Ar file
+listed, evaluating an
+.Ar expression
+(composed of the ``primaries'' and ``operands'' listed below) in terms
+of each file in the tree.
+.Pp
+The options are as follows:
+.Pp
+.Bl -tag -width Ds
+.It Fl H
+The
+.Fl H
+option causes the file information and file type (see
+.Xr stat 2)
+returned for each symbolic link specified on the command line to be 
+those of the file referenced by the link, not the link itself.
+If the referenced file does not exist, the file information and type will
+be for the link itself.  File information of all symbolic links not on 
+the command line is that of the link itself.
+.It Fl L
+The
+.Fl L
+option causes the file information and file type (see
+.Xr stat 2)
+returned for each symbolic link to be those of the file referenced by the
+link, not the link itself.
+If the referenced file does not exist, the file information and type will
+be for the link itself.
+.It Fl P
+The
+.Fl P
+option causes the file information and file type (see
+.Xr stat 2)
+returned for each symbolic link to be those of the link itself.
+.It Fl X
+The
+.Fl X
+option is a modification to permit
+.Nm
+to be safely used in conjunction with
+.Xr xargs 1 .
+If a file name contains any of the delimiting characters used by
+.Xr xargs ,
+a diagnostic message is displayed on standard error, and the file
+is skipped.
+The delimiting characters include single (`` ' '') and double (`` " '')
+quotes, backslash (``\e''), space, tab and newline characters.
+.It Fl d
+The
+.Fl d
+option causes
+.Nm find
+to perform a depth\-first traversal, i.e. directories
+are visited in post\-order and all entries in a directory will be acted
+on before the directory itself.
+By default,
+.Nm find
+visits directories in pre\-order, i.e. before their contents.
+Note, the default is
+.Ar not
+a breadth\-first traversal.
+.It Fl f
+The
+.Fl f
+option specifies a file hierarchy for
+.Nm find
+to traverse.
+File hierarchies may also be specified as the operands immediately
+following the options.
+.It Fl x
+The
+.Fl x
+option prevents
+.Nm find
+from descending into directories that have a device number different
+than that of the file from which the descent began.
+.El
+.Sh PRIMARIES
+.Bl -tag -width Ds
+.It Ic -atime Ar n 
+True if the difference between the file last access time and the time
+.Nm find
+was started, rounded up to the next full 24\-hour period, is
+.Ar n
+24\-hour periods.
+.It Ic -ctime Ar n 
+True if the difference between the time of last change of file status
+information and the time
+.Nm find
+was started, rounded up to the next full 24\-hour period, is
+.Ar n
+24\-hour periods.
+.It Ic -exec Ar utility Op argument ... ; 
+True if the program named
+.Ar utility
+returns a zero value as its exit status.
+Optional arguments may be passed to the utility.
+The expression must be terminated by a semicolon (``;'').
+If the string ``{}'' appears anywhere in the utility name or the
+arguments it is replaced by the pathname of the current file.
+.Ar Utility
+will be executed from the directory from which
+.Nm find
+was executed.
+.It Ic -fstype Ar type 
+True if the file is contained in a file system of type
+.Ar type .
+The
+.Xr sysctl 8
+command can be used to find out the types of filesystems
+that are available on the system:
+.Bd -literal -offset indent
+sysctl vfs
+.Ed
+In addition, there are two pseudo-types, ``local'' and ``rdonly''.
+The former matches any file system physically mounted on the system where
+the
+.Nm find
+is being executed and the latter matches any file system which is
+mounted read-only.
+.It Ic -group Ar gname 
+True if the file belongs to the group
+.Ar gname  .

 If
 If

-.I onum
-is prefixed by a minus sign,
-more flag bits (017777, see
-.IR   stat (2))
-become significant and
-the flags are compared:
-.IR (flags&onum)==onum .
-.TP
-.BR \-type " c"
-True if the type of the file
-is
-.I c,
-where
-.I c
-is
-.B "b, c, d, f, l"
-or
-.B s
-for
-block special file, character special file,
-directory, plain file, symbolic link, or socket.
-.TP
-.BR \-links " n"
+.Ar gname
+is numeric and there is no such group name, then
+.Ar gname
+is treated as a group id.
+.It Ic -inum Ar n 
+True if the file has inode number
+.Ar n  .
+.It Ic -links Ar n 

 True if the file has
 True if the file has

-.I n
+.Ar n

 links.
 links.

-.TP
-.BR \-user " uname"
+.It Ic -ls
+This primary always evaluates to true.
+The following information for the current file is written to standard output:
+its inode number, size in 512\-byte blocks, file permissions, number of hard
+links, owner, group, size in bytes, last modification time, and pathname.
+If the file is a block or character special file, the major and minor numbers
+will be displayed instead of the size in bytes.
+If the file is a symbolic link, the pathname of the linked\-to file will be
+displayed preceded by ``\->''.
+The format is identical to that produced by ``ls \-dgils''.
+.It Ic -mtime Ar n 
+True if the difference between the file last modification time and the time
+.Nm find
+was started, rounded up to the next full 24\-hour period, is
+.Ar n
+24\-hour periods.
+.It Ic \&-ok Ar utility Op argument ... ; 
+The
+.Ic \&-ok
+primary is identical to the
+.Ic -exec
+primary with the exception that
+.Nm find
+requests user affirmation for the execution of the utility by printing
+a message to the terminal and reading a response.
+If the response is other than ``y'' the command is not executed and the
+value of the
+.Ar \&ok
+expression is false.
+.It Ic -name Ar pattern 
+True if the last component of the pathname being examined matches
+.Ar pattern  .
+Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
+may be used as part of
+.Ar pattern  .
+These characters may be matched explicitly by escaping them with a
+backslash (``\e'').
+.It Ic -newer Ar file 
+True if the current file has a more recent last modification time than
+.Ar file  .
+.It Ic -nouser
+True if the file belongs to an unknown user.
+.It Ic -nogroup
+True if the file belongs to an unknown group.
+.It Ic -path Ar pattern 
+True if the pathname being examined matches
+.Ar pattern  .
+Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
+may be used as part of
+.Ar pattern  .
+These characters may be matched explicitly by escaping them with a
+backslash (``\e'').
+Slashes (``/'') are treated as normal characters and do not have to be
+matched explicitly.
+.It Ic -perm Op Fl Ns Ar mode 
+The
+.Ar mode
+may be either symbolic (see
+.Xr chmod  1  )
+or an octal number.
+If the mode is symbolic, a starting value of zero is assumed and the
+mode sets or clears permissions without regard to the process' file mode
+creation mask.
+If the mode is octal, only bits 07777
+.Pf ( Dv S_ISUID
+|
+.Dv S_ISGID
+|
+.Dv S_ISTXT
+|
+.Dv S_IRWXU
+|
+.Dv S_IRWXG
+|
+.Dv S_IRWXO )
+of the file's mode bits participate
+in the comparison.
+If the mode is preceded by a dash (``\-''), 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 (``\-'').
+.It Ic -print
+This primary always evaluates to true.
+It prints the pathname of the current file to standard output.
+If none of
+.Ic -exec ,
+.Ic -ls ,
+or
+.Ic \&-ok
+is specified, the given expression shall be effectively replaced by
+.Cm \&( Ns Ar given\& expression Ns Cm \&) 
+.Ic -print .
+.It Ic -prune
+This primary always evaluates to true.
+It causes
+.Nm find
+to not descend into the current file.
+Note, the
+.Ic -prune
+primary has no effect if the
+.Fl d
+option was specified.
+.It Ic -size Ar n Ns Op Cm c 
+True if the file's size, rounded up, in 512\-byte blocks is
+.Ar n  .
+If
+.Ar n
+is followed by a ``c'', then the primary is true if the
+file's size is
+.Ar n
+bytes.
+.It Ic -type Ar t 
+True if the file is of the specified type.
+Possible file types are as follows:
+.Pp
+.Bl -tag -width flag -offset indent -compact
+.It Cm b
+block special
+.It Cm c
+character special
+.It Cm d
+directory
+.It Cm f
+regular file
+.It Cm l
+symbolic link
+.It Cm p
+FIFO
+.It Cm s
+socket
+.El
+.Pp
+.It Ic -user Ar uname 

 True if the file belongs to the user
 True if the file belongs to the user

-.I uname
-(login name or numeric user ID).
-.TP
-.B \-nouser
-True if the file belongs to a user
-.I not
-in the /etc/passwd database.
-.TP
-.BR \-group " gname"
-True if the file belongs to group
-.I gname
-(group name or numeric group ID).
-.TP
-.B \-nogroup
-True if the file belongs to a group
-.I not
-in the /etc/group database.
-.TP
-.BR \-size " n"
-True if the file is
-.I n
-blocks long (512 bytes per block).
-.TP
-.BR \-inum " n"
-True if the file has inode number
-.I n.
-.TP
-.BR \-atime " n"
-True if the file has been accessed in
-.I n
-days.
-.TP
-.BR \-mtime " n"
-True if the file has been modified in
-.I n
-days.
-.TP
-.BR \-exec " command"
-True if the executed command returns
-a zero value as exit status.
-The end of the command must be punctuated by an escaped
-semicolon.
-A command argument `{}' is replaced by the
-current pathname.
-.TP
-.BR \-ok " command"
-Like
-.B \-exec
-except that the generated command is written on
-the standard output, then the standard input is read
-and the command executed only upon response
-.BR y .
-.TP
-.B  \-print
-Always true;
-causes the current pathname to be printed.
-.TP
-.B  \-ls
-Always true;
-causes current pathname to be printed together
-with its associated statistics.
-These include (respectively) inode number,
-size in kilobytes (1024 bytes),
-protection mode,
-number of hard links,
-user,
-group,
-size in bytes,
-and modification time.
-If the file is a special file
-the size field will instead contain the major and minor
-device numbers.
-If the file is a symbolic link the
-pathname of the linked-to file is printed preceded by ``->''.
-The format is identical to that of ``ls -gilds''
-(note however that formatting is done internally,
-without executing the ls program).
-.TP
-.BR \-newer " file"
-True if
-the current file has been modified more recently than the argument
-.I file.
-.TP
-.BR \-cpio " file"
-Write the current file on the argument
-.I file
-in
-.I cpio
-format.
-.TP
-.B \-xdev
-Always true;
-causes find
-.I not
-to traverse down into a file system different
-from the one on which current
-.I argument
-pathname resides.
-.PP
-The primaries may be combined using the following operators
-(in order of decreasing precedence):
-.TP 4
-1)
-A parenthesized group of primaries and operators
-(parentheses are special to the Shell and must be escaped).
-.TP 4
-2)
-The negation of a primary
-(`!' is the unary
-.I not
-operator).
-.TP 4
-3)
-Concatenation of primaries
-(the
-.I and
-operation
-is implied by the juxtaposition of two primaries).
-.TP 4
-4)
-Alternation of primaries
-.RB "(`" \-o "' is the"
-.I or
-operator).
-.SH EXAMPLES
-.PP
-To find all accessible files whose pathname contains `find':
-.IP
-find find
-.PP
-To typeset all variants of manual pages for `ls':
-.IP 
-vtroff -man `find '*man*/ls.?'`
-.PP
-To remove all files named
-`a.out' or `*.o' that have not been accessed for a week:
-.IP "" .2i
-find / \e( \-name a.out \-o \-name '*.o' \e) \-atime +7 \-exec rm {} \e\;
-.SH FILES
-.nf
-.ta \w'/usr/lib/find/find.codes     'u
-/etc/passwd
-/etc/group
-/usr/lib/find/find.codes       coded pathnames database
-.fi
-.SH "SEE ALSO"
-sh(1), test(1), fs(5)
-.br
-Relevant paper in February, 1983 issue of
-.I ;login:.
-.SH BUGS
-The first form's syntax is painful, and
-the second form's exact semantics is confusing and
-can vary from site to site.
-.PP
-More than one `-newer' option does not work properly.
+.Ar uname  .
+If
+.Ar uname
+is numeric and there is no such user name, then
+.Ar uname
+is treated as a user id.
+.El
+.Pp
+All primaries which take a numeric argument allow the number to be
+preceded by a plus sign (``+'') or a minus sign (``\-'').
+A preceding plus sign means ``more than n'', a preceding minus sign means
+``less than n'' and neither means ``exactly n'' .
+.Sh OPERATORS
+The primaries may be combined using the following operators.
+The operators are listed in order of decreasing precedence.
+.Bl -tag -width (expression) 
+.It Cm \&( Ns Ar expression Ns Cm \&) 
+This evaluates to true if the parenthesized expression evaluates to
+true.
+.Pp
+.It Cm \&! Ns Ar expression 
+This is the unary
+.Tn NOT
+operator.
+It evaluates to true if the expression is false.
+.Pp
+.It Ar expression Cm -and Ar expression 
+.It Ar expression expression 
+The
+.Cm -and
+operator is the logical
+.Tn AND
+operator.
+As it is implied by the juxtaposition of two expressions it does not
+have to be specified.
+The expression evaluates to true if both expressions are true.
+The second expression is not evaluated if the first expression is false.
+.Pp
+.It Ar expression Cm -or Ar expression 
+The
+.Cm -or
+operator is the logical
+.Tn OR
+operator.
+The expression evaluates to true if either the first or the second expression
+is true.
+The second expression is not evaluated if the first expression is true.
+.El
+.Pp
+All operands and primaries must be separate arguments to
+.Nm find  .
+Primaries which themselves take arguments expect each argument
+to be a separate argument to
+.Nm find  .
+.Sh EXAMPLES
+.Pp
+The following examples are shown as given to the shell:
+.Bl -tag -width findx
+.It Li "find  /  \e!  -name  \*q*.c\*q  -print"
+Print out a list of all the files whose names do not end in ``.c''.
+.It Li "find  /  -newer  ttt  -user  wnj  -print"
+Print out a list of all the files owned by user ``wnj'' that are newer
+than the file ``ttt''.
+.It Li "find  /  \e!  \e(  -newer  ttt  -user  wnj  \e)  -print"
+Print out a list of all the files which are not both newer than ``ttt''
+and owned by ``wnj''.
+.It Li "find  /  \e(  -newer  ttt  -or  -user wnj  \e)  -print"
+Print out a list of all the files that are either owned by ``wnj'' or
+that are newer than ``ttt''.
+.El
+.Sh SEE ALSO
+.Xr chmod 1 ,
+.Xr locate 1 ,
+.Xr stat 2 ,
+.Xr fts 3 ,
+.Xr getgrent 3 ,
+.Xr getpwent 3 ,
+.Xr strmode 3 ,
+.Xr symlink 7
+.Sh STANDARDS
+The
+.Nm find
+utility syntax is a superset of the syntax specified by the
+.St -p1003.2
+standard.
+.Pp
+The
+.Fl s
+and
+.Fl X
+options and the
+.Ic -inum
+and
+.Ic -ls
+primaries are extensions to
+.St -p1003.2 .
+.Pp
+Historically, the
+.Fl d ,
+.Fl h
+and
+.Fl x
+options were implemented using the primaries ``\-depth'', ``\-follow'',
+and ``\-xdev''.
+These primaries always evaluated to true.
+As they were really global variables that took effect before the traversal
+began, some legal expressions could have unexpected results.
+An example is the expression ``\-print \-o \-depth''.
+As \-print always evaluates to true, the standard order of evaluation
+implies that \-depth would never be evaluated.
+This is not the case.
+.Pp
+The operator ``-or'' was implemented as ``\-o'', and the operator ``-and''
+was implemented as ``\-a''.
+.Pp
+Historic implementations of the
+.Ic exec
+and
+.Ic ok
+primaries did not replace the string ``{}'' in the utility name or the
+utility arguments if it had preceding or following non-whitespace characters.
+This version replaces it no matter where in the utility name or arguments
+it appears.
+.Sh BUGS
+The special characters used by
+.Nm find
+are also special characters to many shell programs.
+In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'',
+``!'', ``\e'' and ``;'' may have to be escaped from the shell.
+.Pp
+As there is no delimiter separating options and file names or file
+names and the
+.Ar expression ,
+it is difficult to specify files named ``-xdev'' or ``!''.
+These problems are handled by the
+.Fl f
+option and the
+.Xr getopt 3
+``--'' construct.