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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
find(1)				 User Commands			       find(1)

NAME
       find - find files

SYNOPSIS
       /usr/bin/find path... expression

       /usr/xpg4/bin/find path... expression

DESCRIPTION
       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  will  be  able to descend to arbitrary depths in a	file hierarchy
       and will	not fail due to	path length limitations	(unless	a path operand
       specified by the	application exceeds PATH_MAX requirements).

OPERANDS
       The following operands are supported:

       path  A path name of a starting point in	the directory hierarchy.

       expression
	     The  first	 argument  that	starts with a -, or is a ! or a	(, and
	     all subsequent arguments will be  interpreted  as	an  expression
	     made up of	the following primaries	and operators. In the descrip-
	     tions, wherever n is used as  a  primary  argument,  it  will  be
	     interpreted  as  a	 decimal integer optionally preceded by	a plus
	     (+) or minus (-) sign, as follows:

	     +n	   more	than n

	     n	   exactly n

	     -n	   less	than n

   Expressions
       Valid expressions are:

       -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	direc-
	     tory 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 semicolon (;),	the command will be 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	symbolic link pointed to an ancestor. This  expression
	     should not	be used	with the -type l expression.

       -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 system 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. Note that	-local will descend the	hierarchy of non-local
	     directories. See EXAMPLES for an example of  how  to  search  for
	     local files without descending.

       -ls   Always  true.  Prints current path	name together with its associ-
	     ated 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 will instead contain  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)). Note:	Formatting is done internally,
	     without executing the ls program.

       -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)) may be used. A backslash
	     (\) is used as an escape character	within the pattern.  The  pat-
	     tern  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 beginning with '.' will not
	     match pattern when	using /usr/bin/find.  /usr/xpg4/bin/find  does
	     not  make this distinction; wildcard file name generation charac-
	     ters 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 will be
	     identical	 in   format   to  the	symbolic  mode	operand,  sym-
	     bolic_mode_list, described	in chmod(1), and will  be  interpreted
	     as	 follows.  To  start, a	template will be assumed with all file
	     mode bits cleared.	An op symbol of:

	     +	   Will	set the	appropriate mode bits in the template

	     -	   Will	clear the appropriate bits

	     =	   Will	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 character.

       If the hyphen is	omitted, the primary will evaluate 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  will
	     evaluate  as  true	if at least all	the bits in the	resulting tem-
	     plate 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 printed.

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

       -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	special	 file,	direc-
	     tory,  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 may 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
	     juxtaposition of two primaries).

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

       Note:  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 will	be undesirable results.

       If  no  expression  is  present,	-print will be used as the expression.
       Otherwise, if the given expression does not contain  any	 of  the  pri-
       maries  -exec,  -ok or -print, the given	expression will	be effectively
       replaced	by:

	      (	given_expression ) -print

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

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

EXAMPLES
       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
       directory.

       Example 2: Removing files

       Remove 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

       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
       test(1):

       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  will  be
       selected	by:

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

       Example 7: Printing files matching a user's permission mode

       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

       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-
       ries

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

       Example	10:  Printing  the files in the	name space possessing extended
       attributes

       example%	find . -xattr

ENVIRONMENT VARIABLES
       See environ(5) for descriptions of the following	environment  variables
       that  affect  the execution of find: LC_COLLATE,	LC_CTYPE, LC_MESSAGES,
       and NLSPATH.

EXIT STATUS
       The following exit values are returned:

       0     All path operands were traversed successfully.

       >0    An	error occurred.

FILES
       /etc/passwd
	     password file

       /etc/group
	     group file

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

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

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

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

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

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

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

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

SunOS 5.9			  6 Jun	2001			       find(1)

NAME | SYNOPSIS | DESCRIPTION | OPERANDS | USAGE | EXAMPLES | ENVIRONMENT VARIABLES | EXIT STATUS | FILES | ATTRIBUTES | SEE ALSO | WARNINGS | NOTES

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=find&manpath=SunOS+5.9>

home | help