new syntax

[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..c70d624 100644 (file)
--- a/usr/src/usr.bin/find/find.1
+++ b/usr/src/usr.bin/find/find.1
@@ -1,266 +1,383 @@
-.\" 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 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)find.1      6.3 (Berkeley) %G%
+.\" %sccs.include.redist.man%
+.\"
+.\"    @(#)find.1      6.10 (Berkeley) %G%

 .\"
 .TH FIND 1 ""
 .AT 3
 .SH NAME
 .\"
 .TH FIND 1 ""
 .AT 3
 .SH NAME

-find \- find files
+find \- walk a file hierarchy

 .SH SYNOPSIS
 .SH SYNOPSIS

-.B find
-pathname-list expression
-.br 
-.B find
-pattern
+.ft B
+find [ \-dsx ] [ \-f path ] [ path ] expression
+.ft R

 .SH DESCRIPTION
 .SH DESCRIPTION

-In the first form above,
+.I Find
+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
 .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 .
+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
 .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)).
+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
 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.
+.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
 .TP

-.BR \-links " n"
+.B links  n

 True if the file has
 True if the file has

-.I n
+.B n

 links.
 .TP
 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
 .TP

-.B \-nouser
-True if the file belongs to a user
-.I not
-in the /etc/passwd database.
+.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
+.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
 .TP

-.BR \-group " gname"
-True if the file belongs to group
-.I gname
-(group name or numeric group ID).
+.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
 .TP

-.B \-nogroup
-True if the file belongs to a group
-.I not
-in the /etc/group database.
+.B newer file
+True if the current file has a more recent last modification time than
+.BR file .

 .TP
 .TP

-.BR \-size " n"
-True if the file is
-.I n
-blocks long (512 bytes per block).
+.B nouser
+True if the file belongs to an unknown user.

 .TP
 .TP

-.BR \-inum " n"
-True if the file has inode number
-.I n.
+.B nogroup
+True if the file belongs to an unknown group.

 .TP
 .TP

-.BR \-atime " n"
-True if the file has been accessed in
-.I n
-days.
+.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
 .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
 .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).
+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
+.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
 .SH EXAMPLES
 .PP

-To find all accessible files whose pathname contains `find':
-.IP
-find find
+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"
+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
 .PP

-To typeset all variants of manual pages for `ls':
-.IP 
-vtroff -man `find '*man*/ls.?'`
+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
 .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:.
+The second reason is that traversing file trees with names beginning with
+a dash, exclamation point or left parenthesis was impossible.

 .SH BUGS
 .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.
+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.