Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FIND(1)			  BSD General Commands Manual		       FIND(1)

NAME
     find -- walk a file hierarchy

SYNOPSIS
     find [-H |	-L | -P] [-Xdx]	[-f file] [file	...] expression

DESCRIPTION
     Find recursively descends the directory tree for each file	listed,	evalu-
     ating an expression (composed of the ``primaries''	and ``operands''
     listed below) in terms of each file in the	tree.

     The options are as	follows:

     -H	     The -H option causes the file information and file	type (see
	     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 informa-
	     tion 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.

     -L	     The -L option causes the file information and file	type (see
	     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.

     -P	     The -P option causes the file information and file	type (see
	     stat(2)) returned for each	symbolic link to be those of the link
	     itself.  This is the default.

     -X	     The -X option is a	modification to	permit find to be safely used
	     in	conjunction with xargs(1).  If a file name contains any	of the
	     delimiting	characters used	by xargs, a diagnostic message is dis-
	     played on standard	error, and the file is skipped.	 The delimit-
	     ing characters include single (`` ' '') and double	(`` " '')
	     quotes, backslash (``\''),	space, tab and newline characters.

     -d	     The -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 de-
	     fault, find visits	directories in pre-order, i.e. before their
	     contents.	Note, the default is not a breadth-first traversal.

     -f	     The -f option specifies a file hierarchy for find to traverse.
	     File hierarchies may also be specified as the operands immedi-
	     ately following the options.

     -x	     The -x option prevents find from descending into directories that
	     have a device number different than that of the file from which
	     the descent began.

PRIMARIES
     -atime n
	     True if the difference between the	file last access time and the
	     time find was started, rounded up to the next full	24-hour	pe-
	     riod, is n	24-hour	periods.

     -ctime n
	     True if the difference between the	time of	last change of file
	     status information	and the	time find was started, rounded up to
	     the next full 24-hour period, is n	24-hour	periods.

     -delete
	     Delete found files	and/or directories.  Always returns True.
	     This executes from	the current working directory as find recurses
	     down the tree.  It	will not attempt to delete a filename with a
	     ``/'' character in	its pathname relative to "." for security rea-
	     sons.  Depth-first	traversal processing is	implied	by this	op-
	     tion.

     -exec utility [argument ...];
	     True if the program named 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 argu-
	     ments it is replaced by the pathname of the current file.
	     Utility will be executed from the directory from which find was
	     executed.

     -fstype type
	     True if the file is contained in a	file system of type type.
	     Currently supported types are ``local'', ``mfs'', ``nfs'',	``ms-
	     dos'', ``rdonly'' and ``ufs''.  The types ``local'' and
	     ``rdonly''	are not	specific file system types.  The former
	     matches any file system physically	mounted	on the system where
	     the find is being executed	and the	latter matches any file	system
	     which is mounted read-only.

     -group gname
	     True if the file belongs to the group gname.  If gname is numeric
	     and there is no such group	name, then gname is treated as a group
	     id.

     -inum n
	     True if the file has inode	number n.

     -links n
	     True if the file has n links.

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

     -mtime n
	     True if the difference between the	file last modification time
	     and the time find was started, rounded up to the next full
	     24-hour period, is	n 24-hour periods.

     -ok utility[argument ...];
	     The -ok primary is	identical to the -exec primary with the	excep-
	     tion that find requests user affirmation for the execution	of the
	     utility by	printing a message to the terminal and reading a re-
	     sponse.  If the response is other than ``y'' the command is not
	     executed and the value of the ok expression is false.

     -name pattern
	     True if the last component	of the pathname	being examined matches
	     pattern.  Special shell pattern matching characters (``['',
	     ``]'', ``*'', and ``?'')  may be used as part of pattern.	These
	     characters	may be matched explicitly by escaping them with	a
	     backslash (``\'').

     -newer file
	     True if the current file has a more recent	last modification time
	     than file.

     -nouser
	     True if the file belongs to an unknown user.

     -nogroup
	     True if the file belongs to an unknown group.

     -path pattern
	     True if the pathname being	examined matches pattern.  Special
	     shell pattern matching characters (``['', ``]'', ``*'', and
	     ``?'')  may be used as part of pattern.  These characters may be
	     matched explicitly	by escaping them with a	backslash (``\'').
	     Slashes (``/'') are treated as normal characters and do not have
	     to	be matched explicitly.

     -perm [-mode]
	     The mode may be either symbolic (see chmod(1)) or an octal	num-
	     ber.  If the mode is symbolic, a starting value of	zero is	as-
	     sumed and the mode	sets or	clears permissions without regard to
	     the process' file mode creation mask.  If the mode	is octal, only
	     bits 07777	(S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG |
	     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 (``-'').

     -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 none of -exec,	-ls, -print0,
	     or	-ok are	specified.

     -print0
	     This primary always evaluates to true.  It	prints the pathname of
	     the current file to standard output, followed by an ASCII NUL
	     character (character code 0).

     -prune  This primary always evaluates to true.  It	causes find to not de-
	     scend into	the current file.  Note, the -prune primary has	no ef-
	     fect if the -d option was specified.

     -size n[c]
	     True if the file's	size, rounded up, in 512-byte blocks is	n.  If
	     n is followed by a	``c'', then the	primary	is true	if the file's
	     size is n bytes.

     -type t
	     True if the file is of the	specified type.	 Possible file types
	     are as follows:

		   b	 block special
		   c	 character special
		   d	 directory
		   f	 regular file
		   l	 symbolic link
		   p	 FIFO
		   s	 socket

     -user uname
	     True if the file belongs to the user uname.  If uname is numeric
	     and there is no such user name, then uname	is treated as a	user
	     id.

     All primaries which take a	numeric	argument allow the number to be	pre-
     ceded 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'' .

OPERATORS
     The primaries may be combined using the following operators.  The opera-
     tors are listed in	order of decreasing precedence.

     (expression)  This	evaluates to true if the parenthesized expression
		   evaluates to	true.

     !expression   This	is the unary NOT operator.  It evaluates to true if
		   the expression is false.

     expression	-and expression

     expression	expression
		   The -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.

     expression	-or expression
		   The -or operator is the logical OR operator.	 The expres-
		   sion	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.

     All operands and primaries	must be	separate arguments to find.  Primaries
     which themselves take arguments expect each argument to be	a separate ar-
     gument to find.

EXAMPLES
     The following examples are	shown as given to the shell:

     find  /  \!  -name	 "*.c"	-print
	    Print out a	list of	all the	files whose names do not end in
	    ``.c''.

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

     find  /  \!  \(  -newer  ttt  -user  wnj  \)  -print
	    Print out a	list of	all the	files which are	not both newer than
	    ``ttt'' and	owned by ``wnj''.

     find  /  \(  -newer  ttt  -or  -user wnj  \)  -print
	    Print out a	list of	all the	files that are either owned by ``wnj''
	    or that are	newer than ``ttt''.

SEE ALSO
     chmod(1), locate(1), stat(2), fts(3), getgrent(3),	getpwent(3),
     strmode(3), symlink(7)

STANDARDS
     The find utility syntax is	a superset of the syntax specified by the IEEE
     Std 1003.2	("POSIX.2") standard.

     The -s and	-X options and the -inum, -print0, -delete, and	-ls primaries
     are extensions to IEEE Std	1003.2 ("POSIX.2").

     Historically, the -d, -h and -x options were implemented using the	pri-
     maries ``-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.

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

     Historic implementations of the exec and ok primaries did not replace the
     string ``{}'' in the utility name or the utility arguments	if it had pre-
     ceding or following non-whitespace	characters.  This version replaces it
     no	matter where in	the utility name or arguments it appears.

BUGS
     The special characters used by find are also special characters to	many
     shell programs.  In particular, the characters ``*'', ``['', ``]'',
     ``?'', ``('', ``)'', ``!'', ``\'' and ``;'' may have to be	escaped	from
     the shell.

     As	there is no delimiter separating options and file names	or file	names
     and the expression, it is difficult to specify files named	``-xdev'' or
     ``!''.  These problems are	handled	by the -f option and the getopt(3)
     ``--'' construct.

     The -delete primary do not	interact well with other options that cause
     the filesystem tree traversal options to be changed.

HISTORY
     A find command appeared in	Version	1 AT&T UNIX.

BSD				 April 1, 1994				   BSD

NAME | SYNOPSIS | DESCRIPTION | PRIMARIES | OPERATORS | EXAMPLES | SEE ALSO | STANDARDS | BUGS | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=find&manpath=FreeBSD+2.2.5-RELEASE>

home | help