src/usr.bin/find/find.1 - diff

Return to find.1 CVS log

Up to [local] / src / usr.bin / find

Diff for /src/usr.bin/find/find.1 between version 1.21 and 1.22

version 1.21, 1999/05/26 03:29:58

version 1.22, 1999/06/05 01:21:25

Line 48

.Op Ar file ...

.Ar expression

.Sh DESCRIPTION

.Nm find

.Nm

recursively descends the directory tree for each

.Ar file

listed, evaluating an

.Ar expression

(composed of the ``primaries'' and ``operands'' listed below) in terms

(composed of the

.Dq primaries

and

.Dq operands

listed below) in terms

of each file in the tree.

.Pp

The options are as follows:

.Bl -tag -width Ds

.It Fl H

Causes the file information and file type (see

.Xr stat 2 )

returned for each symbolic link encountered 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 d

Causes

.Nm find

.Nm

to perform a depth\-first traversal, i.e. directories

to perform a depth-first traversal, i.e., directories

are visited in post\-order and all entries in a directory will be acted

are visited in post-order and all entries in a directory will be acted

on before the directory itself.

By default,

.Nm find

.Nm

visits directories in pre\-order, i.e. before their contents.

visits directories in pre-order, i.e., before their contents.

Note, the default is

.Ar not

.Em not

a breadth\-first traversal.

a breadth-first traversal.

.It Fl f Ar file

Specifies a file hierarchy for

.Nm find

.Nm

to traverse.

File hierarchies may also be specified as the operands immediately

following the options.

.It Fl h

Causes the file information and file type (see

.Xr stat 2 ) ,

.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

Line 100

Line 104

.Xr xargs ,

a diagnostic message is displayed on standard error, and the file

is skipped.

The delimiting characters include single (``''') and double (``"'')

The delimiting characters include single

quotes, backslash (``\e''), space, tab and newline (``\en'') characters.

.Pq Ql '

and double

.Pq Ql \&"

quotes, backslash

.Pq Ql \e ,

space, tab, and newline

.Pq Sq \en

characters.

As an alternative, the

.Fl print0

function may be used safely in conjunction with the

Line 110

Line 121

.Xr xargs 1 .

.It Fl x

Prevents

.Nm

from descending into directories that have a device number different

than that of the file from which the descent began.

.It Fl W

Line 120

Line 131

.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

.Nm

was started, rounded up to the next full minute, is

.Ar n

minutes.

.It Ic -atime Ar n

True if the difference between the file last access time and the time

.Nm find

.Nm

was started, rounded up to the next full 24\-hour period, is

was started, rounded up to the next full 24-hour period, is

.Ar n

24\-hour periods.

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

.Nm

was started, rounded up to the next full minute, is

.Ar n

minutes.

.It Ic -ctime Ar n

True if the difference between the time of last change of file status

information and the time

.Nm find

.Nm

was started, rounded up to the next full 24\-hour period, is

was started, rounded up to the next full 24-hour period, is

.Ar n

24\-hour periods.

24-hour periods.

.It Ic -empty

True if the current file or directory is empty.

.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 (`;').

The expression must be terminated by a semicolon

If the string ``{}'' appears anywhere in the utility name or the

.Pq Ql \&; .

If the string

.Qq {}

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

.Nm

was executed.

.It Ic -execdir Ar utility Op argument ... ;

The

Identical to 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.

the string

.Qq {}

is not qualified.

.It Ic -follow

Follow symbolic links.

.It Ic -fstype Ar type

True if the file is contained in a file system of type

.Ar type .

Two special file system types are recognized: ``local'' and ``rdonly''.

Two special file system types are recognized:

.Dq local

and

.Dq rdonly .

These do not describe actual file system types;

the former matches any file system physically mounted on the system where

.Nm find

.Nm

is being executed, and the latter matches any file system which is

is being executed whereas 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 .

Line 189

Line 206

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

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

If the file is a symbolic link, the pathname of the linked-to file will be

displayed preceded by ``\->''.

displayed preceded by

The format is identical to that produced by ``ls \-dgils''.

.Dq \-> .

The format is identical to that produced by

.Dq ls \-dgils .

.It Ic -maxdepth Ar n

True if the current search depth is less than or equal to what is specified in

.Ar n .

.It Ic -mindepth Ar n

True if the current search depth is at least what is specified in

.Ar n .

.It Ic -mmin Ar n

True if the difference between the file last modification time and the time

.Nm find

.Nm

was started, rounded up to the next full minute, is

.Ar n

minutes.

.It Ic -mtime Ar n

True if the difference between the file last modification time and the time

.Nm find

.Nm

was started, rounded up to the next full 24\-hour period, is

was started, rounded up to the next full 24-hour period, is

.Ar n

24\-hour periods.

24-hour periods.

.It Ic \&-ok Ar utility Ns Op argument ... ;

.It Ic -name Ar pattern

The

.Ic \&-ok

primary is identical to the

.Ic -exec

primary with the exception that

.Nm find

requests user affirmation for the execution of

.Ar 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

.Ic \&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 ``?'')

Special shell pattern matching characters

.Pf ( Ql [ ,

.Ql \&] ,

.Ql * ,

and

.Ql ? )

may be used as part of

.Ar pattern .

These characters may be matched explicitly by escaping them with a

backslash (`\e').

backslash

.It Ic -newer Ar file

.Pq Ql \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

.It Ic \&-ok Ar utility Op argument ... ;

Identical to the

.Ic -exec

primary with the exception that

.Nm

requests user affirmation for the execution of

.Ar utility

by printing

a message to the terminal and reading a response.

If the response is other than

.Sq y

the command is not executed and the

value of the

.Ic \&ok

expression is false.

.It Ic -path Ar pattern

True if the pathname being examined matches

.Ar pattern .

Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')

Special shell pattern matching characters

.Pf ( Ql [ ,

.Ql \&] ,

.Ql * ,

and

.Ql ? )

may be used as part of

.Ar pattern .

These characters may be matched explicitly by escaping them with a

backslash (`\e').

backslash

Slashes (`/') are treated as normal characters and do not have to be

.Pq Ql \e .

Slashes

.Pq Ql /

are treated as normal characters and do not have to be

matched explicitly.

.It Xo

.Ic -perm

Line 291

Line 324

.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 the mode is preceded by a dash

.Pq Sq \- ,

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

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 (``\-'').

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, followed

by a newline (``\en'') character.

by a newline

.Pq Ql \en

character.

If neither

.Ic -exec ,

.Ic -ls ,

Line 307

Line 344

nor

.Ic -print0

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.

Line 316

Line 353

.It Ic -prune

This primary always evaluates to true.

It causes

.Nm find

.Nm

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

True if the file's size, rounded up, in 512-byte blocks is

.Ar n .

.Ar n

is followed by a ``c'', then the primary is true if the

is followed by a

.Sq 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 W

whiteout (currently, these won't even be visible without also specifying

.Fl W )

.It Cm b

block special

Line 356

Line 395

socket

.El

.Pp

.It Ic -user Ar uname

True if the file belongs to the user

.Ar uname .

Line 367

Line 406

.El

.Pp

All primaries which take a numeric argument allow the number to be

preceded by a plus sign (``+'') or a minus sign (``\-'').

preceded by a plus sign

A preceding plus sign means ``more than n'', a preceding minus sign means

.Pq Ql +

``less than n'', and neither means ``exactly n'' .

or a minus sign

.Pq Ql \- .

A preceding plus sign means

.Dq more than n ,

a preceding minus sign means

.Dq less than n ,

and neither means

.Dq 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

Line 396

Line 442

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

Line 408

Line 454

.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

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''.

Print out a list of all the files whose names do not end in

.Dq .c .

.It Li "find / -newer ttt -user wnj -print"

Print out a list of all the files owned by user ``wnj'' that are newer

Print out a list of all the files owned by user

than the file ``ttt''.

.Dq wnj

that are newer

than the file

.Dq 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''

Print out a list of all the files which are not both newer than

and owned by ``wnj''.

.Dq ttt

and owned by

.Dq 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

Print out a list of all the files that are either owned by

that are newer than ``ttt''.

.Dq wnj

that are newer than

.Dq ttt .

.El

.Sh SEE ALSO

.Xr chmod 1 ,

Line 438

Line 493

.Xr symlink 7

.Sh STANDARDS

The

.Nm find

.Nm

utility syntax is a superset of the syntax specified by the

.St -p1003.2

standard.

Line 474

Line 529

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''.

An example is the expression

As \-print always evaluates to true, the standard order of evaluation

.Dq \-print \-o \-depth .

implies that \-depth would never be evaluated.

.Cm \-print

always evaluates to true, the standard order of evaluation

implies that

.Cm \-depth

would never be evaluated.

This is not the case.

.Pp

The operator ``-or'' was implemented as ``\-o'', and the operator ``-and''

The operator

was implemented as ``\-a''.

.Cm -or

was implemented as

.Cm \-o ,

and the operator

.Cm -and

was implemented as

.Cm \-a .

.Pp

Historic implementations of the

.Ic -exec

and

.Ic -ok

primaries did not replace the string ``{}'' in the utility name or the

primaries did not replace the string

.Qq {}

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

.Nm

are also special characters to many shell programs.

In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'',

In particular, the characters

``!'', ``\e'' and ``;'' may have to be escaped from the shell.

.Ql * ,

.Ql [ ,

.Ql \&] ,

.Ql ? ,

.Ql ( ,

.Ql \&) ,

.Ql ! ,

.Ql \e ,

and

.Ql \&;

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 ``!''.

it is difficult to specify files named

.Dq -xdev

.Dq ! .

These problems are handled by the

.Fl f

option and the

.Xr getopt 3

``--'' construct.

.Dq \-\-

construct.

.Pp

The

.Fl W

option is probably not the most elegant way to handle whiteouts, it may

option is probably not the most elegant way to handle whiteouts. It may

be replaced by a more sophisticated algorithm eventually.