unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

find(1)                          User Commands                         find(1)



NAME
       find - find files

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

       /usr/xpg4/bin/find [-H | -L]  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  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).

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



       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.

OPERANDS
       The following operands are supported:

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



       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



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



       -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
                       EXAMPLES for an example of  how  to  search  for  local
                       files without descending.



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

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



       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.

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

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

       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-
       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: LANG, LC_ALL, LC_COLLATE,  LC_CTYPE,
       LC_MESSAGES, and NLSPATH.

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



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:


       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE  TYPEATTRIBUTE   VALUE   AvailabilitySUNWcsu
       CSIEnabled Interface StabilityStable


SEE ALSO
       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)

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  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, they are not be selected if
       -mount or -xdev is specified in the find expression.



SunOS 5.10                        24 Jun 2004                          find(1)