BSD 4_3_Reno 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 23a3cc9..3f45222 100644 (file)
--- a/usr/src/usr.bin/find/find.1
+++ b/usr/src/usr.bin/find/find.1
@@ -1,172 +1,445 @@
-.\"    @(#)find.1      4.1 (Berkeley) %G%
+.\" Copyright (c) 1990 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.TH FIND 1 
-.AT 3
-.SH NAME
-find \- find files
-.SH SYNOPSIS
-.B find
-pathname-list  expression
-.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)).
+.\" Redistribution and use in source and binary forms are permitted provided
+.\" that: (1) source distributions retain this entire copyright notice and
+.\" comment, and (2) distributions including binaries display the following
+.\" acknowledgement:  ``This product includes software developed by the
+.\" University of California, Berkeley and its contributors'' in the
+.\" documentation or other materials provided with the distribution and in
+.\" all advertising materials mentioning features or use of this software.
+.\" 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 ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
+.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\"     @(#)find.1     6.15 (Berkeley) 7/24/90
+.\"
+.Dd July 24, 1990
+.Dt FIND 1
+.Os BSD 4.4
+.Sh NAME
+.Nm find
+.Nd walk a file hierarchy
+.Sh SYNOPSIS
+.Nm find
+.Op Fl dsx
+.Op Ar path
+.Ar expression
+.Nm find
+.Op Fl dsx
+.Op Fl f Ar path
+.Ar expression
+.Sh DESCRIPTION
+.Nm Find
+recursively descends the directory tree for each
+.Ar path
+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
+.Tw Ds
+.Tp Fl d
+The
+.Fl 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,
+.Nm find
+visits directories in pre\-order, i.e. before their contents.
+Note, the default is
+.Ar not
+a breadth\-first traversal.
+.Tp Fl f
+The
+.Fl f
+option specifies a file hierarchy for
+.Nm find
+to traverse.
+If no
+.Fl f
+option is specified, the first operand after the options is
+expected to be the file hierarchy to be traversed.
+.Tp Fl s
+The
+.Fl s
+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.
+.Tp 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.
+.Tp
+.Sh PRIMARIES
+.Tw Ds
+.Tp Cx Ic atime
+.Cx \&\ \&
+.Ar n
+.Cx
+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.
+.Tp Cx Ic ctime
+.Cx \&\ \&
+.Ar n
+.Cx
+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.
+.Tp Cx Ic exec
+.Cx \&\ \&
+.Ar utility
+.Cx \&\ \&
+.Op argument ... ;
+.Cx
+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.
+Utility will be executed in the directory from which
+.Nm find
+was executed.
+.Tp Cx Ic fstype
+.Cx \&\ \&
+.Ar type
+.Cx
+True if the file is contained in a file system of type
+.Ar type .
+Currently supported types are ``local'', ``mfs'', ``nfs'', ``pc'' and
+``ufs''.
+The type ``local'' is not a specific file system type, but matches
+any file system physically mounted on the system where the
+.Nm find
+is being executed.
+.Tp Cx Ic group
+.Cx \&\ \&
+.Ar gname
+.Cx
+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"
-or
-.B f
-for
-block special file, character special file,
-directory or plain file.
-.TP
-.BR \-links " n"
+.Ar gname
+is numeric and there is no such group name, then
+.Ar gname
+is treated as a group id.
+.Tp Cx Ic inum
+.Cx \&\ \&
+.Ar n
+.Cx
+True if the file has inode number
+.Ar n  .
+.Tp Cx Ic links
+.Cx \&\ \&
+.Ar n
+.Cx

 True if the file has
 True if the file has

-.I n
+.Ar n

 links.
 links.

-.TP
-.BR \-user " uname"
+.Tp 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''.
+.Tp Cx Ic mtime
+.Cx \&\ \&
+.Ar n
+.Cx
+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.
+.Tp Cx Ic \&ok
+.Cx \&\ \&
+.Ar utility
+.Ws
+.Op argument ... ;
+.Cx
+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.
+.Tp Cx Ic name
+.Cx \&\ \&
+.Ar pattern
+.Cx
+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'').
+.Tp Cx Ic newer
+.Cx \&\ \&
+.Ar file
+.Cx
+True if the current file has a more recent last modification time than
+.Ar file  .
+.Tp Ic nouser
+True if the file belongs to an unknown user.
+.Tp Ic nogroup
+True if the file belongs to an unknown group.
+.Tp Cx Ic perm
+.Cx \&\ \&
+.Op Fl
+.Ar mode
+.Cx
+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 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 Ic 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
+.Ic exec  ,
+.Ic ls ,
+or
+.Ic \&ok
+is specified.
+.Tp Ic prune
+This primary always evaluates to true.
+It causes
+.Nm find
+to not descend into the current file.
+.Tp Cx Ic size
+.Cx \&\ \&
+.Ar n
+.Op Cm c
+.Cx
+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.
+.Tp Cx Ic type
+.Cx \&\ \&
+.Ar t
+.Cx
+True if the file is of the specified type.
+Possible file types are as follows:
+.Pp
+.Df I
+.Tw Ds
+.Tp Cm b
+block special
+.Tp Cm c
+character special
+.Tp Cm d
+directory
+.Tp Cm f
+regular file
+.Tp Cm l
+symbolic link
+.Tp Cm p
+FIFO
+.Tp Cm s
+socket
+.Tp
+.De
+.Pp
+.Tp Cx Ic user
+.Cx \&\ \&
+.Ar uname
+.Cx

 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
-.BR \-group " gname"
-True if the file belongs to group
-.I gname
-(group name or numeric group ID).
-.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
-.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
-.br
-/etc/group
-.SH "SEE ALSO"
-sh(1), test(1), filsys(5)
-.SH BUGS
-The syntax is painful.
+.Ar uname  .
+If
+.Ar uname
+is numeric and there is no such user name, then
+.Ar uname
+is treated as a user id.
+.Tp
+.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
+.Ar n  ' ' ,
+a preceding minus sign means ``less than
+.Ar n  ' '
+and neither means ``exactly
+.Ar n  ' ' .
+.Sh OPERATORS
+The primaries may be combined using the following operators.
+The operators are listed in order of decreasing precedence.
+.Di L
+.Dp Cx Ic \&(
+.Ar expression
+.Cx \&)
+.Cx
+This evaluates to true if the parenthesized expression evaluates to
+true.
+.Pp
+.Dp Cx Ic \&!
+.Cx \&\ \&
+.Ar expression
+.Cx
+This is the unary NOT operator.
+It evaluates to true if the expression is false.
+.Pp
+.Dp Cx Ar expression
+.Cx \&\ \&
+.Ic and
+.Cx \&\ \&
+.Ar expression
+.Cx
+.Dp Cx Ar expression expression
+.Cx
+The
+.Ic 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.
+.Pp
+.Dp Cx Ar expression
+.Cx \&\ \&
+.Ic or
+.Cx \&\ \&
+.Ar expression
+.Cx
+The
+.Ic 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.
+.Dp
+.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:
+.Tw findx
+.Tp Li find  /  \e!  name  "*.c"  print
+Print out a list of all the files whose names do not end in ``.c''.
+.Tp 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''.
+.Tp 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''.
+.Tp 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''.
+.Tp
+.Sh SEE ALSO
+.Xr chmod 1 ,
+.Xr sh 1 ,
+.Xr test 1 ,
+.Xr stat 2 ,
+.Xr umask 2 ,
+.Xr getpwent 3 ,
+.Xr getgrent 3 ,
+.Xr strmode 3
+.Sh STANDARDS
+The
+.Nm 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
+.Fl s
+option as well as the primaries
+.Ic inum
+and
+.Ic ls
+are extensions to the POSIX standard.
+.Sh COMPATIBILITY
+The traditional, and standardized, syntax for
+.Nm find
+is as follows.
+All of the primaries are preceded by a dash (``\-''), i.e. the
+primary ``group'' is specified as ``\-group''.
+The
+.Fl d  ,
+.Fl s ,
+and
+.Fl 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
+.Nm 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
+.Nm 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 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.