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

FreeBSD Manual Pages


home | help
find(1)								       find(1)

       find - find files

       /usr/bin/find [-H | -L]	path...	expression

       /usr/xpg4/bin/find [-H |	-L]  path... expression

       The  find utility recursively descends the directory hierarchy for each
       path seeking files that match a Boolean expression written in the  pri-
       maries given below.

       find  is	 able  to  descend to arbitrary	depths in a file hierarchy and
       does not	fail due to path length	limitations  (unless  a	 path  operand
       specified by the	application exceeds PATH_MAX requirements).

       The following options are supported:

       -H	Causes	the  file information and file type evaluated for each
		symbolic link encountered on the command line to be  those  of
		the  file  referenced by the link, and not the link itself. If
		the referenced file does not exist, the	file  information  and
		type is	for the	link itself. File information for all symbolic
		links not on the command line is that of the link itself.

       -L	Causes the file	information and	file type evaluated  for  each
		symbolic  link to be those of the file referenced by the link,
		and not	the link itself. See NOTES.

       Specifying more than one	of the mutually-exclusive options -H and -L is
       not  considered	an  error.  The	 last  option specified	determines the
       behavior	of the utility.

       The following operands are supported:

       path	       A path name of a	starting point in the directory	 hier-

       expression      The first argument that starts with a -,	or is a	! or a
		       (, and all subsequent arguments are interpreted	as  an
		       expression made up of the following primaries and oper-
		       ators. In the descriptions, wherever n  is  used	 as  a
		       primary	argument, it is	interpreted as a decimal inte-
		       ger optionally preceded by a  plus  (+)	or  minus  (-)
		       sign, as	follows:

		       +n	more than n

		       n	exactly	n

		       -n	less than n

       Valid expressions are:

       -acl	       True if the file	have additional	ACLs defined.

       -atime n	       True  if	 the  file was accessed	n days ago. The	access
		       time of directories in path is changed by find  itself.

       -cpio device    Always  true. Writes the	current	file on	device in cpio
		       format (5120-byte records).

       -ctime n	       True if the file's status was changed n days ago.

       -depth	       Always true. Causes descent of the directory  hierarchy
		       to be done so that all entries in a directory are acted
		       on before the directory itself.	 This  can  be	useful
		       when  find  is used with	cpio(1)	to transfer files that
		       are contained in	directories without write  permission.

       -exec command   True  if	 the  executed command returns a zero value as
		       exit status. The	end of command must be	punctuated  by
		       an  escaped  semicolon  (;).   A	command	argument {} is
		       replaced	by the current path name. If the last argument
		       to  -exec is {} and you specify + rather	than the semi-
		       colon (;), the command is invoked fewer times, with  {}
		       replaced	by groups of pathnames.

       -follow	       Always true. Causes symbolic links to be	followed. When
		       following symbolic  links,  find	 keeps	track  of  the
		       directories  visited  so	 that  it  can detect infinite
		       loops. For example, such	a loop would occur if  a  sym-
		       bolic  link  pointed  to	 an  ancestor. This expression
		       should not be used with the  -type  l  expression.  See

       -fstype type    True  if	the filesystem to which	the file belongs is of
		       type type.

       -group gname    True if the file	belongs	to the group gname.  If	 gname
		       is  numeric and does not	appear in the /etc/group file,
		       or in the NIS/NIS+ tables, it is	taken as a group ID.

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

       -links n	       True if the file	has n links.

       -local	       True if the file	system type is not a remote file  sys-
		       tem  type  as defined in	the /etc/dfs/fstypes file. nfs
		       is used as the default remote filesystem	 type  if  the
		       /etc/dfs/fstypes	file is	not present. The -local	option
		       descends	the hierarchy of  non-local  directories.  See
		       for an example of how to	search for local files without

       -ls	       Always true. Prints current path	name together with its
		       associated statistics. These include (respectively):

			 o  inode number

			 o  size in kilobytes (1024 bytes)

			 o  protection mode

			 o  number of hard links

			 o  user

			 o  group

			 o  size in bytes

			 o  modification time.

		       If  the	file is	a special file,	the size field instead
		       contains	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 (see ls(1B)).

		       Formatting is done internally, without executing	the ls

       -mount	       Always  true.  Restricts	 the search to the file	system
		       containing the directory	specified. Does	not list mount
		       points to other file systems.

       -mtime n	       True if the file's data was modified n days ago.

       -name pattern   True  if	 pattern matches the current file name.	Normal
		       shell file name generation characters (see  sh(1))  can
		       be used.	A backslash (\)	is used	as an escape character
		       within the pattern. The pattern should  be  escaped  or
		       quoted when find	is invoked from	the shell.

		       Unless the character '.'	is explicitly specified	in the
		       beginning      of pattern, a current file  name	begin-
		       ning  with  '.'	does  not  match  pattern  when	 using
		       /usr/bin/find. /usr/xpg4/bin/find does  not  make  this
		       distinction;  wildcard  file name generation characters
		       can match file names beginning with '.'.

       -ncpio device   Always true. Writes the current file on device in  cpio
		       -c format (5120 byte records).

       -newer file     True  if	 the  current  file  has  been	modified  more
		       recently	than the argument file.

       -nogroup	       True if	the  file  belongs  to	a  group  not  in  the
		       /etc/group file,	or in the NIS/NIS+ tables.

       -nouser	       True  if	 the  file  belongs  to	 a  user  not  in  the
		       /etc/passwd file, or in the NIS/NIS+ tables.

       -ok command     Like -exec, except that the generated command  line  is
		       printed	with  a	 question  mark	first, and is executed
		       only if the user	responds by typing y.

       -perm [-]mode   The mode	argument is used to represent file mode	 bits.
		       It is identical in format to the	symbolic mode operand,
		       symbolic_mode_list,  described  in  chmod(1),  and   is
		       interpreted as follows. To start, a template is assumed
		       with all	file mode bits cleared.	An op symbol of:

		       +	Set the	appropriate mode bits in the template

		       -	Clear the appropriate bits

		       =	Set the	appropriate mode bits, without	regard
				to the contents	of the file mode creation mask
				of the process

		       The op symbol of	- cannot be  the  first	 character  of
		       mode,  to  avoid	 ambiguity  with  the optional leading
		       hyphen. Since the initial mode is all bits  off,	 there
		       are  no	symbolic modes that need to use	- as the first

		       If the hyphen is	omitted, the primary evaluates as true
		       when  the  file permission bits exactly match the value
		       of the resulting	template.

		       Otherwise, if mode is prefixed by a hyphen, the primary
		       evaluates  as  true  if	at  least  all the bits	in the
		       resulting template are set in the file permission bits.

       -perm [-]onum   True  if	 the  file  permission flags exactly match the
		       octal number onum (see chmod(1)). If onum  is  prefixed
		       by a minus sign (-), only the bits that are set in onum
		       are compared with the file permission  flags,  and  the
		       expression evaluates true if they match.

       -print	       Always  true.  Causes  the  current  path  name	to  be

       -prune	       Always yields true. Does	not examine any	directories or
		       files in	the directory structure	below the pattern just
		       matched.	(See ).	If -depth is specified,	-prune has  no

       -size n[c]      True  if	 the  file  is	n  blocks  long	(512 bytes per
		       block). If n is followed	by a c,	the size is in	bytes.

       -type c	       True  if	the type of the	file is	c, where c is b, c, d,
		       D, f, l,	p, or s	for block special file,	character spe-
		       cial  file, directory, door, plain file,	symbolic link,
		       fifo (named pipe), or socket, respectively.

       -user uname     True if the file	belongs	to the user uname. If uname is
		       numeric	and  does  not	appear	as a login name	in the
		       /etc/passwd file, or in	the  NIS/NIS+  tables,	it  is
		       taken as	a user ID.

       -xdev	       Same as the -mount primary.

       -xattr	       True if the file	has extended attributes.

   Complex Expressions
       The  primaries  can be combined using the following operators (in order
       of decreasing precedence):

       1)   ( expression )	       True if the parenthesized expression is
				       true  (parentheses  are	special	to the
				       shell and must be escaped).

       2)   ! expression	       The negation of a  primary  (!  is  the
				       unary not operator).

       3) expression [-a] expression   Concatenation  of  primaries  (the  and
				       operation is implied by the  juxtaposi-
				       tion of two primaries).

       4)  expression -o expression    Alternation  of primaries (-o is	the or

       When you	use find in conjunction	with cpio, if you use  the  -L	option
       with  cpio  then	you must use the -follow expression with find and vice
       versa. Otherwise	there are undesirable results.

       If no expression	is present, -print is used as the  expression.	Other-
       wise,  if  the  given  expression does not contain any of the primaries
       -exec, -ok or -print, the given expression is effectively replaced by:

	      (	given_expression ) -print

       The -user, -group, and -newer primaries each evaluate their  respective
       arguments  only	once.  Invocation of command specified by -exec	or -ok
       does not	affect subsequent primaries on the same	file.

       See largefile(5)	for the	description  of	 the  behavior	of  find  when
       encountering files greater than or equal	to 2 Gbyte ( 2**31 bytes).

       Example 1: Writing Out the Hierarchy Directory

       The following commands are equivalent:

       example%	find .
       example%	find . -print

       They  both  write  out  the entire directory hierarchy from the current

       Example 2: Removing Files

       The following comand removes all	files in  your	home  directory	 named
       a.out or	*.o that have not been accessed	for a week:

       example%	find $HOME \( -name a.out -o -name '*.o' \) \
	      -atime +7	-exec rm {} \;

       Example 3: Printing All File Names But Skipping SCCS Directories

       The  following  command recursively print all file names	in the current
       directory and below, but	skipping SCCS directories:

       example%	find . -name SCCS -prune -o -print

       Example 4: Printing all file names and the SCCS directory name

       Recursively print all file names	in the current	directory  and	below,
       skipping	 the  contents	of SCCS	directories, but printing out the SCCS
       directory name:

       example%	find . -print -name SCCS -prune

       Example 5: Testing for the Newer	File

       The following command is	basically equivalent to	the -nt	 extension  to

       example$	if [ -n	"$(find
       file1 -prune -newer file2)" ]; then

       printf %s\\n "file1 is newer than file2"

       Example 6: Selecting a File Using 24-hour Mode

       The  descriptions  of  -atime, -ctime, and -mtime use the terminology n
       ``24-hour periods''. For	example, a file	accessed at 23:59 is  selected

       example%	find . -atime -1 print

       at  00:01 the next day (less than 24 hours later, not more than one day
       ago). The midnight boundary between days	has no effect on  the  24-hour

       Example 7: Printing Files Matching a User's Permission Mode

       The following command recursively print all file	names whose permission
       mode exactly matches read, write, and execute access for	user, and read
       and execute access for group and	other:

       example%	find . -perm u=rwx,g=rx,o=rx

       The above could alternatively be	specified as follows:

       example%	find . -perm a=rwx,g-w,o-w

       Example 8: Printing Files with Write Access for other

       The following command recursively print all file	names whose permission
       includes, but is	not limited to,	write access for other:

       example%	find . -perm -o+w

       Example 9: Printing Local Files without Descending  Non-local  Directo-

       example%	find . ! -local	-prune -o -print

       Example	10:  Printing  the Files in the	Name Space Possessing Extended

       example%	find . -xattr

       See environ(5) for descriptions of the following	environment  variables
       that  affect the	execution of find: LANG, LC_ALL, LC_COLLATE, LC_CTYPE,

       PATH	       Determine the location  of  the	utility_name  for  the
		       -exec and -ok primaries.

       The following exit values are returned:

       0	All path operands were traversed successfully.

       >0	An error occurred.

       /etc/passwd	       Password	file

       /etc/group	       Group file

       /etc/dfs/fstypes	       File  that  registers  distributed  file	system

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWcsu			   |
       |CSI			     |Enabled			   |
       |Interface Stability	     |Stable			   |

       chmod(1), cpio(1), ls(1B), sh(1), test(1), acl(2),  stat(2),  umask(2),
       attributes(5), environ(5), fsattr(5), largefile(5), standards(5)

       The  following options are obsolete and will not	be supported in	future

       -cpio device    Always true. Writes the current file on device in  cpio
		       format (5120-byte records).

       -ncpio device   Always  true. Writes the	current	file on	device in cpio
		       -c format (5120-byte records).

       When using find to determine files modified within a range of time, use
       the  -mtime  argument before the	-print argument. Otherwise, find gives
       all files.

       Some files that might be	under the Solaris root file system  are	 actu-
       ally  mount  points  for	virtual	file systems, such as mntfs or namefs.
       When comparing against a	ufs file system, such files are	 not  selected
       if -mount or -xdev is specified in the find expression.

       Using  the  -L  or  -follow option is not recommended when descending a
       file-system hierarchy that is under the control of other	users. In par-
       ticular,	when using -exec, symbolic links can lead the find command out
       of the hierarchy	in which it started. Using -type is not	sufficient  to
       restrict	the type of files on which the -exec command operates, because
       there is	an inherent race condition between the type-check performed by
       the find	command	and the	time the executed command operates on the file

				 15 July 2005			       find(1)


Want to link to this manual page? Use this URL:

home | help