X-Git-Url: https://git.subgeniuskitty.com/unix-history/.git/blobdiff_plain/5710a779dff3831a0fef249785411a166f5b39af..202dd4ce070b42fff294eb5621255250845cdb3b:/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 4534c04778..c70d624a0d 100644
--- a/usr/src/usr.bin/find/find.1
+++ b/usr/src/usr.bin/find/find.1
@@ -1,172 +1,383 @@
-.\"	@(#)find.1	5.1 (Berkeley) %G%
+.\" Copyright (c) 1990 The Regents of the University of California.
+.\" All rights reserved.
 .\"
-.TH FIND 1  "18 January 1983"
+.\" %sccs.include.redist.man%
+.\"
+.\"	@(#)find.1	6.10 (Berkeley) %G%
+.\"
+.TH FIND 1 ""
 .AT 3
 .SH NAME
-find \- find files
+find \- walk a file hierarchy
 .SH SYNOPSIS
-.B find
-pathname-list  expression
+.ft B
+find [ \-dsx ] [ \-f path ] [ path ] expression
+.ft R
 .SH DESCRIPTION
 .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 .
-.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)).
+recursively descends the directory tree for each
+.I path
+listed, evaluating an ``expression'' (composed of the ``primaries''
+and ``operands'' listed below) in terms of each file in the tree.
+.PP
+The options are as follows:
+.TP
+.B \-d
+The
+.B \-d
+option causes 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,
+.I find
+visits directories in pre\-order, i.e. before their contents.
+Note, the default is
+.I not
+a breadth\-first traversal.
+.TP
+.B \-f
+The
+.B \-f
+option specifies a file hierarchy for
+.I find
+to traverse.
+If no
+.B \-f
+option is specified, the first operand after the options is
+expected to be the file to be traversed.
+.TP
+.B \-s
+The
+.B \-s
+option causes the file information and file type (see
+.IR 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.
+.TP
+.B \-x
+The
+.B \-x
+option causes
+.I find
+to not descend into directories that have a different device number
+than the file the descent began from.
+.PP
+Operands and primaries must each be a separate argument to
+.IR find .
+Primaries which themselves take arguments expect each argument
+to be a separate argument to
+.IR find .
+.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
+.BR n '',
+a preceding minus sign means ``less than
+.BR n ''
+and neither means ``exactly
+.BR n ''.
+.SH PRIMARIES
+.TP
+.B atime n
+True if the difference between the file last access time and the time
+.I find
+was started, rounded up to the next full 24\-hour period, is
+.B n
+24\-hour periods.
+.TP
+.B ctime n
+True if the difference between the time of last change of file status
+information and the time
+.I find
+was started, rounded up to the next full 24\-hour period, is
+.B n
+24\-hour periods.
+.TP
+.B exec  utility  [argument ...]  ;
+True if the program named
+.B 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.
+Utility will be executed in the directory from which
+.I find
+was executed.
+.TP
+.B fstype type
+True if the file is contained in a file system of type
+.BR type.
+Currently supported types are ``mfs'', ``nfs'', ``pc'' and ``ufs''.
+.TP
+.B group gname
+True if the file belongs to the group
+.BR gname .
 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"
-or
-.B l
-for
-block special file, character special file,
-directory, plain file, or symbolic link.
+.B gname
+is numeric and there is no such group name, then
+.B gname
+is treated as a group id.
+.TP
+.B inum n
+True if the file has inode number
+.BR n .
 .TP
-.BR \-links " n"
+.B links  n
 True if the file has
-.I n
+.B n
 links.
 .TP
-.BR \-user " uname"
-True if the file belongs to the user
-.I uname
-(login name or numeric user ID).
+.B 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''.
 .TP
-.BR \-group " gname"
-True if the file belongs to group
-.I gname
-(group name or numeric group ID).
+.B mtime n
+True if the difference between the file last modification time and the time
+.I find
+was started, rounded up to the next full 24\-hour period, is
+.B n
+24\-hour periods.
 .TP
-.BR \-size " n"
-True if the file is
-.I n
-blocks long (512 bytes per block).
+.B ok  utility  [argument ...]  ;
+The
+.B ok
+primary is identical to the
+.B exec
+primary with the exception that
+.I 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
+.B ok
+expression is false.
 .TP
-.BR \-inum " n"
-True if the file has inode number
-.I n.
+.B name pattern
+True if the last component of the pathname being examined matches
+.BR pattern .
+Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
+may be used as part of
+.BR pattern .
+These characters may be matched explicitly by escaping them with a
+backslash (``\e'').
 .TP
-.BR \-atime " n"
-True if the file has been accessed in
-.I n
-days.
+.B newer file
+True if the current file has a more recent last modification time than
+.BR file .
+.TP
+.B nouser
+True if the file belongs to an unknown user.
+.TP
+.B nogroup
+True if the file belongs to an unknown group.
+.TP
+.B perm [\-]mode
+The
+.B mode
+may be either symbolic (see
+.IR 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 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 (``\-'').
 .TP
-.BR \-mtime " n"
-True if the file has been modified in
+.B print
+This primary always evaluates to true.
+It prints the pathname of the current file to standard output.
+The expression is appended to the user specified expression if neither
+.BR exec ,
+.BR ls ,
+or
+.B ok
+is specified.
+.TP
+.B prune
+This primary always evaluates to true.
+It causes
+.I find
+to not descend into the current file.
+.TP
+.B size n[c]
+True if the file's size, rounded up, in 512\-byte blocks is
+.BR n .
+If 
+.B n
+is followed by a ``c'', then the primary is true if the
+file's size is 
 .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
-.BR \-newer " file"
-True if
-the current file has been modified more recently than the argument
-.I file.
-.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 EXAMPLE
-To remove all files named
-`a.out' or `*.o' that have not been accessed for a week:
-.IP "" .2i
-find / \\( \-name a.out \-o \-name '*.o' \\)
-\-atime +7 \-exec rm {} \\;
-.SH FILES
-/etc/passwd
+bytes.
+.TP
+.B type t
+True if the file is of the specified type.
+Possible file types are as follows:
+.RS
+.TP
+.B b
+block special
+.br
+.ns
+.TP
+.B c
+character special
+.br
+.ns
+.TP
+.B d
+directory
+.br
+.ns
+.TP
+.B f
+regular file
+.br
+.ns
+.TP
+.B l
+symbolic link
+.br
+.ns
+.TP
+.B p
+FIFO
+.br
+.ns
+.TP
+.B s
+socket
+.RE
+.TP
+.B user uname
+True if the file belongs to the user
+.BR uname .
+If
+.B uname
+is numeric and there is no such user name, then
+.B uname
+is treated as a user id.
+.SH OPERATORS
+The primaries may be combined using the following operators.
+The operators are listed in order of decreasing precedence.
+.TP
+.B "( expression )"
+This evaluates to true if the parenthesized expression evaluates to
+true.
+.TP
+.B "! expression"
+This is the unary NOT operator.
+It evaluates to true if the expression is false.
+.TP
+.B "expression and expression"
 .br
-/etc/group
+.ns
+.TP
+.B "expression expression"
+The
+.B and
+operator is the logical 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.
+.TP
+.B "expression or expression"
+The
+.B or
+operator is the logical 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.
+.SH EXAMPLES
+.PP
+The following examples are shown as given to the shell:
+.TP
+find  /  \e!  name  "*.c"  print
+Print out a list of all the files whose names do not end in ``.c''.
+.TP
+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''.
+.TP
+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''.
+.TP
+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''.
 .SH "SEE ALSO"
-sh(1), test(1), fs(5)
+chmod(1), sh(1), test(1), stat(2), umask(2),
+getpwent(3), getgrent(3), strmode(3)
+.SH STANDARDS
+The
+.I find
+utility syntax is a replacement for the syntax specified by the POSIX
+1003.2 standard.
+The standard syntax is also supported; see the COMPATIBILITY section
+below for details.
+.PP
+The
+.B \-s
+option as well as the primaries
+.B inum
+and
+.BR ls
+are extensions to the POSIX standard.
+.SH COMPATIBILITY
+The traditional, and standardized, syntax for
+.I find
+is as follows.
+All of the primaries are preceded by a dash (``\-''), i.e. the
+primary ``group'' is specified as ``\-group''.
+The
+.BR \-d ,
+.BR \-s ,
+and
+.BR \-x
+options are implemented using the primaries ``\-depth'', ``\-follow'',
+and ``\-xdev''.
+These primaries always evaluate to true.
+The operator ``or'' is implemented as ``\-o'', and the operator
+``and'' is implemented as ``\-a''.
+The set of file trees to be traversed are specified as the first operands
+to
+.IR find .
+The first operand beginning with a dash (``\-''), exclamation point (``!'')
+or left parenthesis (``('') is assumed to be the beginning of the expression
+and the end of the files to be traversed.
+.PP
+The
+.I find
+syntax was changed for two reasons.
+The first is that the ``\-depth'', ``\-follow'' and ``\-xdev'' primaries
+are really global variables that take effect before the traversal begins.
+This causes some legal expressions to 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 second reason is that traversing file trees with names beginning with
+a dash, exclamation point or left parenthesis was impossible.
 .SH BUGS
-The syntax is painful.
+The special characters used by
+.I find
+are also special characters to many shell programs.
+In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'',
+``!'', ``\e'' and ``;'' may have to be escaped from the shell.