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 be-
       havior 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 re-
		       placed 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  di-
		       rectories visited so that it can	detect infinite	loops.
		       For example, such a loop	would occur if a symbolic link
		       pointed	to  an ancestor. This expression should	not be
		       used with the -type l expression. See NOTES.

       -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  re-
		       cently 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 in-
		       terpreted 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  hy-
		       phen. Since the initial mode is all bits	off, there are
		       no symbolic modes that need to use - as the first char-

		       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  re-
		       sulting template	are set	in the file permission bits.

       -perm [-]onum   True if the file	permission flags exactly match the oc-
		       tal 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 op-
				       eration is implied by the juxtaposition
				       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 en-
       countering 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 di-

       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