Return to find.1 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / usr.bin / find

Annotation of 43BSDReno/usr.bin/find/find.1, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1990 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted provided
        !             5: .\" that: (1) source distributions retain this entire copyright notice and
        !             6: .\" comment, and (2) distributions including binaries display the following
        !             7: .\" acknowledgement:  ``This product includes software developed by the
        !             8: .\" University of California, Berkeley and its contributors'' in the
        !             9: .\" documentation or other materials provided with the distribution and in
        !            10: .\" all advertising materials mentioning features or use of this software.
        !            11: .\" Neither the name of the University nor the names of its contributors may
        !            12: .\" be used to endorse or promote products derived from this software without
        !            13: .\" specific prior written permission.
        !            14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
        !            15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
        !            16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            17: .\"
        !            18: .\"     @(#)find.1     6.15 (Berkeley) 7/24/90
        !            19: .\"
        !            20: .Dd July 24, 1990
        !            21: .Dt FIND 1
        !            22: .Os BSD 4.4
        !            23: .Sh NAME
        !            24: .Nm find
        !            25: .Nd walk a file hierarchy
        !            26: .Sh SYNOPSIS
        !            27: .Nm find
        !            28: .Op Fl dsx
        !            29: .Op Ar path
        !            30: .Ar expression
        !            31: .Nm find
        !            32: .Op Fl dsx
        !            33: .Op Fl f Ar path
        !            34: .Ar expression
        !            35: .Sh DESCRIPTION
        !            36: .Nm Find
        !            37: recursively descends the directory tree for each
        !            38: .Ar path
        !            39: listed, evaluating an
        !            40: .Ar expression
        !            41: (composed of the ``primaries'' and ``operands'' listed below) in terms
        !            42: of each file in the tree.
        !            43: .Pp
        !            44: The options are as follows:
        !            45: .Pp
        !            46: .Tw Ds
        !            47: .Tp Fl d
        !            48: The
        !            49: .Fl d
        !            50: option causes find to perform a depth\-first traversal, i.e. directories
        !            51: are visited in post\-order and all entries in a directory will be acted
        !            52: on before the directory itself.
        !            53: By default,
        !            54: .Nm find
        !            55: visits directories in pre\-order, i.e. before their contents.
        !            56: Note, the default is
        !            57: .Ar not
        !            58: a breadth\-first traversal.
        !            59: .Tp Fl f
        !            60: The
        !            61: .Fl f
        !            62: option specifies a file hierarchy for
        !            63: .Nm find
        !            64: to traverse.
        !            65: If no
        !            66: .Fl f
        !            67: option is specified, the first operand after the options is
        !            68: expected to be the file hierarchy to be traversed.
        !            69: .Tp Fl s
        !            70: The
        !            71: .Fl s
        !            72: option causes the file information and file type (see
        !            73: .Xr stat  2  ) ,
        !            74: returned for each symbolic link to be those of the file referenced by the
        !            75: link, not the link itself.
        !            76: If the referenced file does not exist, the file information and type will
        !            77: be for the link itself.
        !            78: .Tp Fl x
        !            79: The
        !            80: .Fl x
        !            81: option prevents
        !            82: .Nm find
        !            83: from descending into directories that have a device number different
        !            84: than that of the file from which the descent began.
        !            85: .Tp
        !            86: .Sh PRIMARIES
        !            87: .Tw Ds
        !            88: .Tp Cx Ic atime
        !            89: .Cx \&\ \&
        !            90: .Ar n
        !            91: .Cx
        !            92: True if the difference between the file last access time and the time
        !            93: .Nm find
        !            94: was started, rounded up to the next full 24\-hour period, is
        !            95: .Ar n
        !            96: 24\-hour periods.
        !            97: .Tp Cx Ic ctime
        !            98: .Cx \&\ \&
        !            99: .Ar n
        !           100: .Cx
        !           101: True if the difference between the time of last change of file status
        !           102: information and the time
        !           103: .Nm find
        !           104: was started, rounded up to the next full 24\-hour period, is
        !           105: .Ar n
        !           106: 24\-hour periods.
        !           107: .Tp Cx Ic exec
        !           108: .Cx \&\ \&
        !           109: .Ar utility
        !           110: .Cx \&\ \&
        !           111: .Op argument ... ;
        !           112: .Cx
        !           113: True if the program named
        !           114: .Ar utility
        !           115: returns a zero value as its exit status.
        !           116: Optional arguments may be passed to the utility.
        !           117: The expression must be terminated by a semicolon (``;'').
        !           118: If the string ``{}'' appears anywhere in the utility name or the
        !           119: arguments it is replaced by the pathname of the current file.
        !           120: Utility will be executed in the directory from which
        !           121: .Nm find
        !           122: was executed.
        !           123: .Tp Cx Ic fstype
        !           124: .Cx \&\ \&
        !           125: .Ar type
        !           126: .Cx
        !           127: True if the file is contained in a file system of type
        !           128: .Ar type .
        !           129: Currently supported types are ``local'', ``mfs'', ``nfs'', ``pc'' and
        !           130: ``ufs''.
        !           131: The type ``local'' is not a specific file system type, but matches
        !           132: any file system physically mounted on the system where the
        !           133: .Nm find
        !           134: is being executed.
        !           135: .Tp Cx Ic group
        !           136: .Cx \&\ \&
        !           137: .Ar gname
        !           138: .Cx
        !           139: True if the file belongs to the group
        !           140: .Ar gname  .
        !           141: If
        !           142: .Ar gname
        !           143: is numeric and there is no such group name, then
        !           144: .Ar gname
        !           145: is treated as a group id.
        !           146: .Tp Cx Ic inum
        !           147: .Cx \&\ \&
        !           148: .Ar n
        !           149: .Cx
        !           150: True if the file has inode number
        !           151: .Ar n  .
        !           152: .Tp Cx Ic links
        !           153: .Cx \&\ \&
        !           154: .Ar n
        !           155: .Cx
        !           156: True if the file has
        !           157: .Ar n
        !           158: links.
        !           159: .Tp Ic ls
        !           160: This primary always evaluates to true.
        !           161: The following information for the current file is written to standard output:
        !           162: its inode number, size in 512\-byte blocks, file permissions, number of hard
        !           163: links, owner, group, size in bytes, last modification time, and pathname.
        !           164: If the file is a block or character special file, the major and minor numbers
        !           165: will be displayed instead of the size in bytes.
        !           166: If the file is a symbolic link, the pathname of the linked\-to file will be
        !           167: displayed preceded by ``\->''.
        !           168: The format is identical to that produced by ``ls \-dgils''.
        !           169: .Tp Cx Ic mtime
        !           170: .Cx \&\ \&
        !           171: .Ar n
        !           172: .Cx
        !           173: True if the difference between the file last modification time and the time
        !           174: .Nm find
        !           175: was started, rounded up to the next full 24\-hour period, is
        !           176: .Ar n
        !           177: 24\-hour periods.
        !           178: .Tp Cx Ic \&ok
        !           179: .Cx \&\ \&
        !           180: .Ar utility
        !           181: .Ws
        !           182: .Op argument ... ;
        !           183: .Cx
        !           184: The
        !           185: .Ic \&ok
        !           186: primary is identical to the
        !           187: .Ic exec
        !           188: primary with the exception that
        !           189: .Nm find
        !           190: requests user affirmation for the execution of the utility by printing
        !           191: a message to the terminal and reading a response.
        !           192: If the response is other than ``y'' the command is not executed and the
        !           193: value of the
        !           194: .Ar \&ok
        !           195: expression is false.
        !           196: .Tp Cx Ic name
        !           197: .Cx \&\ \&
        !           198: .Ar pattern
        !           199: .Cx
        !           200: True if the last component of the pathname being examined matches
        !           201: .Ar pattern  .
        !           202: Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
        !           203: may be used as part of
        !           204: .Ar pattern  .
        !           205: These characters may be matched explicitly by escaping them with a
        !           206: backslash (``\e'').
        !           207: .Tp Cx Ic newer
        !           208: .Cx \&\ \&
        !           209: .Ar file
        !           210: .Cx
        !           211: True if the current file has a more recent last modification time than
        !           212: .Ar file  .
        !           213: .Tp Ic nouser
        !           214: True if the file belongs to an unknown user.
        !           215: .Tp Ic nogroup
        !           216: True if the file belongs to an unknown group.
        !           217: .Tp Cx Ic perm
        !           218: .Cx \&\ \&
        !           219: .Op Fl
        !           220: .Ar mode
        !           221: .Cx
        !           222: The
        !           223: .Ar mode
        !           224: may be either symbolic (see
        !           225: .Xr chmod  1  )
        !           226: or an octal number.
        !           227: If the mode is symbolic, a starting value of zero is assumed and the
        !           228: mode sets or clears permissions without regard to the process' file mode
        !           229: creation mask.
        !           230: If the mode is octal, only bits 07777 of the file's mode bits participate
        !           231: in the comparison.
        !           232: If the mode is preceded by a dash (``\-''), this primary evaluates to true
        !           233: if at least all of the bits in the mode are set in the file's mode bits.
        !           234: If the mode is not preceded by a dash, this primary evaluates to true if
        !           235: the bits in the mode exactly match the file's mode bits.
        !           236: Note, the first character of a symbolic mode may not be a dash (``\-'').
        !           237: .Tp Ic print
        !           238: This primary always evaluates to true.
        !           239: It prints the pathname of the current file to standard output.
        !           240: The expression is appended to the user specified expression if neither
        !           241: .Ic exec  ,
        !           242: .Ic ls ,
        !           243: or
        !           244: .Ic \&ok
        !           245: is specified.
        !           246: .Tp Ic prune
        !           247: This primary always evaluates to true.
        !           248: It causes
        !           249: .Nm find
        !           250: to not descend into the current file.
        !           251: .Tp Cx Ic size
        !           252: .Cx \&\ \&
        !           253: .Ar n
        !           254: .Op Cm c
        !           255: .Cx
        !           256: True if the file's size, rounded up, in 512\-byte blocks is
        !           257: .Ar n  .
        !           258: If
        !           259: .Ar n
        !           260: is followed by a ``c'', then the primary is true if the
        !           261: file's size is
        !           262: .Ar n
        !           263: bytes.
        !           264: .Tp Cx Ic type
        !           265: .Cx \&\ \&
        !           266: .Ar t
        !           267: .Cx
        !           268: True if the file is of the specified type.
        !           269: Possible file types are as follows:
        !           270: .Pp
        !           271: .Df I
        !           272: .Tw Ds
        !           273: .Tp Cm b
        !           274: block special
        !           275: .Tp Cm c
        !           276: character special
        !           277: .Tp Cm d
        !           278: directory
        !           279: .Tp Cm f
        !           280: regular file
        !           281: .Tp Cm l
        !           282: symbolic link
        !           283: .Tp Cm p
        !           284: FIFO
        !           285: .Tp Cm s
        !           286: socket
        !           287: .Tp
        !           288: .De
        !           289: .Pp
        !           290: .Tp Cx Ic user
        !           291: .Cx \&\ \&
        !           292: .Ar uname
        !           293: .Cx
        !           294: True if the file belongs to the user
        !           295: .Ar uname  .
        !           296: If
        !           297: .Ar uname
        !           298: is numeric and there is no such user name, then
        !           299: .Ar uname
        !           300: is treated as a user id.
        !           301: .Tp
        !           302: .Pp
        !           303: All primaries which take a numeric argument allow the number to be
        !           304: preceded by a plus sign (``+'') or a minus sign (``\-'').
        !           305: A preceding plus sign means ``more than
        !           306: .Ar n  ' ' ,
        !           307: a preceding minus sign means ``less than
        !           308: .Ar n  ' '
        !           309: and neither means ``exactly
        !           310: .Ar n  ' ' .
        !           311: .Sh OPERATORS
        !           312: The primaries may be combined using the following operators.
        !           313: The operators are listed in order of decreasing precedence.
        !           314: .Di L
        !           315: .Dp Cx Ic \&(
        !           316: .Ar expression
        !           317: .Cx \&)
        !           318: .Cx
        !           319: This evaluates to true if the parenthesized expression evaluates to
        !           320: true.
        !           321: .Pp
        !           322: .Dp Cx Ic \&!
        !           323: .Cx \&\ \&
        !           324: .Ar expression
        !           325: .Cx
        !           326: This is the unary NOT operator.
        !           327: It evaluates to true if the expression is false.
        !           328: .Pp
        !           329: .Dp Cx Ar expression
        !           330: .Cx \&\ \&
        !           331: .Ic and
        !           332: .Cx \&\ \&
        !           333: .Ar expression
        !           334: .Cx
        !           335: .Dp Cx Ar expression expression
        !           336: .Cx
        !           337: The
        !           338: .Ic and
        !           339: operator is the logical AND operator.
        !           340: As it is implied by the juxtaposition of two expressions it does not
        !           341: have to be specified.
        !           342: The expression evaluates to true if both expressions are true.
        !           343: The second expression is not evaluated if the first expression is false.
        !           344: .Pp
        !           345: .Dp Cx Ar expression
        !           346: .Cx \&\ \&
        !           347: .Ic or
        !           348: .Cx \&\ \&
        !           349: .Ar expression
        !           350: .Cx
        !           351: The
        !           352: .Ic or
        !           353: operator is the logical OR operator.
        !           354: The expression evaluates to true if either the first or the second expression
        !           355: is true.
        !           356: The second expression is not evaluated if the first expression is true.
        !           357: .Dp
        !           358: .Pp
        !           359: All operands and primaries must be separate arguments to
        !           360: .Nm find  .
        !           361: Primaries which themselves take arguments expect each argument
        !           362: to be a separate argument to
        !           363: .Nm find  .
        !           364: .Sh EXAMPLES
        !           365: .Pp
        !           366: The following examples are shown as given to the shell:
        !           367: .Tw findx
        !           368: .Tp Li find  /  \e!  name  "*.c"  print
        !           369: Print out a list of all the files whose names do not end in ``.c''.
        !           370: .Tp Li find  /  newer  ttt  user  wnj  print
        !           371: Print out a list of all the files owned by user ``wnj'' that are newer
        !           372: than the file ``ttt''.
        !           373: .Tp Li find  /  \e!  \e(  newer  ttt  user  wnj  \e)  print
        !           374: Print out a list of all the files which are not both newer than ``ttt''
        !           375: and owned by ``wnj''.
        !           376: .Tp Li find  /  \e(  newer  ttt  or  user wnj  \e)  print
        !           377: Print out a list of all the files that are either owned by ``wnj'' or
        !           378: that are newer than ``ttt''.
        !           379: .Tp
        !           380: .Sh SEE ALSO
        !           381: .Xr chmod 1 ,
        !           382: .Xr sh 1 ,
        !           383: .Xr test 1 ,
        !           384: .Xr stat 2 ,
        !           385: .Xr umask 2 ,
        !           386: .Xr getpwent 3 ,
        !           387: .Xr getgrent 3 ,
        !           388: .Xr strmode 3
        !           389: .Sh STANDARDS
        !           390: The
        !           391: .Nm find
        !           392: utility syntax is a replacement for the syntax specified by the POSIX
        !           393: 1003.2 standard.
        !           394: The standard syntax is also supported; see the COMPATIBILITY section
        !           395: below for details.
        !           396: .Pp
        !           397: The
        !           398: .Fl s
        !           399: option as well as the primaries
        !           400: .Ic inum
        !           401: and
        !           402: .Ic ls
        !           403: are extensions to the POSIX standard.
        !           404: .Sh COMPATIBILITY
        !           405: The traditional, and standardized, syntax for
        !           406: .Nm find
        !           407: is as follows.
        !           408: All of the primaries are preceded by a dash (``\-''), i.e. the
        !           409: primary ``group'' is specified as ``\-group''.
        !           410: The
        !           411: .Fl d  ,
        !           412: .Fl s ,
        !           413: and
        !           414: .Fl x
        !           415: options are implemented using the primaries ``\-depth'', ``\-follow'',
        !           416: and ``\-xdev''.
        !           417: These primaries always evaluate to true.
        !           418: The operator ``or'' is implemented as ``\-o'', and the operator
        !           419: ``and'' is implemented as ``\-a''.
        !           420: The set of file trees to be traversed are specified as the first operands
        !           421: to
        !           422: .Nm find  .
        !           423: The first operand beginning with a dash (``\-''), exclamation point (``!'')
        !           424: or left parenthesis (``('') is assumed to be the beginning of the expression
        !           425: and the end of the files to be traversed.
        !           426: .Pp
        !           427: The
        !           428: .Nm find
        !           429: syntax was changed for two reasons.
        !           430: The first is that the ``\-depth'', ``\-follow'' and ``\-xdev'' primaries
        !           431: are really global variables that take effect before the traversal begins.
        !           432: This causes some legal expressions to have unexpected results.
        !           433: An example is the expression ``\-print \-o \-depth''.
        !           434: As \-print always evaluates to true, the standard order of evaluation
        !           435: implies that \-depth would never be evaluated.
        !           436: This is not the case.
        !           437: .Pp
        !           438: The second reason is that traversing file trees with names beginning with
        !           439: a dash, exclamation point or left parenthesis was impossible.
        !           440: .Sh BUGS
        !           441: The special characters used by
        !           442: .Nm find
        !           443: are also special characters to many shell programs.
        !           444: In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'',
        !           445: ``!'', ``\e'' and ``;'' may have to be escaped from the shell.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.