539 lines
15 KiB
Groff
539 lines
15 KiB
Groff
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" the Institute of Electrical and Electronics Engineers, Inc.
|
|
.\"
|
|
.\" 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
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.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 Xdsx
|
|
.Op Fl f Ar pathname
|
|
.Op Ar pathname ...
|
|
.Ar expression
|
|
.Sh DESCRIPTION
|
|
.Nm Find
|
|
recursively descends the directory tree for each
|
|
.Ar pathname
|
|
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.
|
|
This is the default.
|
|
.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 s
|
|
The
|
|
.Fl s
|
|
option causes
|
|
.Nm find
|
|
to traverse the file hierarchies in lexicographical order,
|
|
i.e., alphabetical order within each directory.
|
|
Note:
|
|
.Sq find -s
|
|
and
|
|
.So
|
|
find | sort
|
|
.Sc
|
|
may give different results.
|
|
.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 -amin 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 minutes period, is
|
|
.Ar n
|
|
minutes periods.
|
|
.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 -cmin 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 minutes period, is
|
|
.Ar n
|
|
minutes 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 -delete
|
|
Delete found files and/or directories.
|
|
Always returns true.
|
|
This executes
|
|
from the current working directory as
|
|
.Nm
|
|
recurses down the tree.
|
|
It will not attempt to delete a filename with a ``/''
|
|
character in its pathname relative to "." for security reasons.
|
|
Depth\-first traversal processing is implied by this option.
|
|
.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 -execdir Ar utility Op argument ... ;
|
|
The
|
|
.Ic \&-execdir
|
|
primary is identical to 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 ``{}'' is not qualified.
|
|
.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
|
|
.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
|
|
.Ar n
|
|
links.
|
|
.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 -mmin 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 minutes period, is
|
|
.Ar n
|
|
minutes periods.
|
|
.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 Xo
|
|
.Ic -perm
|
|
.Op Fl
|
|
.Ar mode
|
|
.Xc
|
|
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 ,
|
|
.Ic -print0 ,
|
|
or
|
|
.Ic \&-ok
|
|
is specified, the given expression shall be effectively replaced by
|
|
.Cm \&( Ns Ar given\& expression Ns Cm \&)
|
|
.Ic -print .
|
|
.It Ic -print0
|
|
This primary always evaluates to true.
|
|
It prints the pathname of the current file to standard output, followed by an
|
|
.Tn ASCII
|
|
.Tn NUL
|
|
character (character code 0).
|
|
.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
|
|
.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 \&( Ar expression Cm \&)
|
|
This evaluates to true if the parenthesized expression evaluates to
|
|
true.
|
|
.Pp
|
|
.It Cm \&! 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 whereis 1 ,
|
|
.Xr which 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
|
|
All the single character options as well as the
|
|
.Ic -inum ,
|
|
.Ic -print0 ,
|
|
.Ic -delete ,
|
|
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.
|
|
.Pp
|
|
The
|
|
.Ic -delete
|
|
primary does not interact well with other options that cause the filesystem
|
|
tree traversal options to be changed.
|
|
.Sh HISTORY
|
|
A
|
|
.Nm
|
|
command appeared in
|
|
.At v1 .
|