--- find.texi 29 Jun 2005 10:43:22 -0400 1.92 +++ find.texi 29 Jun 2005 16:05:16 -0400 @@ -45,14 +45,14 @@ @end ignore Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the entire -resulting derived work is distributed under the terms of a permission -notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation approved -by the Foundation. +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. @end copying @titlepage @@ -74,6 +74,7 @@ This file documents the GNU utilities for finding files that match certain criteria and performing various actions on them. + This is edition @value{EDITION}, for @code{find} version @value{VERSION}. @end ifnottex @@ -95,21 +96,22 @@ @node Introduction, Finding Files, Top, Top @chapter Introduction -This manual shows how to find files that meet criteria you specify, and -how to perform various actions on the files that you find. The -principal programs that you use to perform these tasks are @code{find}, -@code{locate}, and @code{xargs}. Some of the examples in this manual -use capabilities specific to the GNU versions of those programs. - -GNU @code{find} was originally written by Eric Decker, with enhancements -by David MacKenzie, Jay Plett, and Tim Wood. GNU @code{xargs} was -originally written by Mike Rendell, with enhancements by David -MacKenzie. GNU @code{locate} and its associated utilities were -originally written by James Woods, with enhancements by David MacKenzie. -The idea for @samp{find -print0} and @samp{xargs -0} came from Dan -Bernstein. The current maintainer of GNU findutils (and this manual) is -James Youngman. Many other people have contributed bug fixes, small -improvements, and helpful suggestions. Thanks! +This manual shows how to find files that meet criteria you specify, +and how to perform various actions on the files that you find. The +principal programs that you use to perform these tasks are +@code{find}, @code{locate}, and @code{xargs}. Some of the examples in +this manual use capabilities specific to the GNU versions of those +programs. + +GNU @code{find} was originally written by Eric Decker, with +enhancements by David MacKenzie, Jay Plett, and Tim Wood. GNU +@code{xargs} was originally written by Mike Rendell, with enhancements +by David MacKenzie. GNU @code{locate} and its associated utilities +were originally written by James Woods, with enhancements by David +MacKenzie. The idea for @samp{find -print0} and @samp{xargs -0} came +from Dan Bernstein. The current maintainer of GNU findutils (and this +manual) is James Youngman. Many other people have contributed bug +fixes, small improvements, and helpful suggestions. Thanks! Mail suggestions and bug reports for these programs to @code{bug-findutils@@gnu.org}. Please include the version @@ -124,12 +126,12 @@ @node Scope @section Scope -For brevity, the word @dfn{file} in this manual means a regular file, a -directory, a symbolic link, or any other kind of node that has a -directory entry. A directory entry is also called a @dfn{file name}. A -file name may contain some, all, or none of the directories in a path -that leads to the file. These are all examples of what this manual -calls ``file names'': +For brevity, the word @dfn{file} in this manual means a regular file, +a directory, a symbolic link, or any other kind of node that has a +directory entry. A directory entry is also called a @dfn{file name}. +A file name may contain some, all, or none of the directories in a +path that leads to the file. These are all examples of what this +manual calls ``file names'': @example parser.c @@ -139,9 +141,9 @@ /usr/local/include/termcap.h @end example -A @dfn{directory tree} is a directory and the files it contains, all of -its subdirectories and the files they contain, etc. It can also be a -single non-directory file. +A @dfn{directory tree} is a directory and the files it contains, all +of its subdirectories and the files they contain, etc. It can also be +a single non-directory file. These programs enable you to find the files in one or more directory trees that: @@ -172,9 +174,9 @@ Once you have found the files you're looking for (or files that are potentially the ones you're looking for), you can do more to them than simply list their names. You can get any combination of the files' -attributes, or process the files in many ways, either individually or in -groups of various sizes. Actions that you might want to perform on the -files you have found include, but are not limited to: +attributes, or process the files in many ways, either individually or +in groups of various sizes. Actions that you might want to perform on +the files you have found include, but are not limited to: @itemize @bullet @item @@ -207,9 +209,9 @@ @end example @noindent -Here is a typical use of @code{find}. This example prints the names of -all files in the directory tree rooted in @file{/usr/src} whose name -ends with @samp{.c} and that are larger than 100 Kilobytes. +Here is a typical use of @code{find}. This example prints the names +of all files in the directory tree rooted in @file{/usr/src} whose +name ends with @samp{.c} and that are larger than 100 Kilobytes. @example find /usr/src -name '*.c' -size +100k -print @end example @@ -227,18 +229,18 @@ @noindent This example prints the names of all files in the default file name -database whose name ends with @samp{Makefile} or @samp{makefile}. Which -file names are stored in the database depends on how the system +database whose name ends with @samp{Makefile} or @samp{makefile}. +Which file names are stored in the database depends on how the system administrator ran @code{updatedb}. @example locate '*[Mm]akefile' @end example -The name @code{xargs}, pronounced EX-args, means ``combine arguments.'' -@code{xargs} builds and executes command lines by gathering together -arguments it reads on the standard input. Most often, these arguments -are lists of file names generated by @code{find}. @code{xargs} is run -like this: +The name @code{xargs}, pronounced EX-args, means ``combine +arguments.'' @code{xargs} builds and executes command lines by +gathering together arguments it reads on the standard input. Most +often, these arguments are lists of file names generated by +@code{find}. @code{xargs} is run like this: @example xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]} @@ -255,15 +257,16 @@ @node find Expressions @section @code{find} Expressions -The expression that @code{find} uses to select files consists of one or -more @dfn{primaries}, each of which is a separate command line argument -to @code{find}. @code{find} evaluates the expression each time it -processes a file. An expression can contain any of the following types -of primaries: +The expression that @code{find} uses to select files consists of one +or more @dfn{primaries}, each of which is a separate command line +argument to @code{find}. @code{find} evaluates the expression each +time it processes a file. An expression can contain any of the +following types of primaries: @table @dfn @item options -affect overall operation rather than the processing of a specific file; +affect overall operation rather than the processing of a specific +file; @item tests return a true or false value, depending on the file's attributes; @item actions @@ -276,17 +279,17 @@ You can omit the operator between two primaries; it defaults to @samp{-and}. @xref{Combining Primaries With Operators}, for ways to connect primaries into more complex expressions. If the expression -contains no actions other than @samp{-prune}, @samp{-print} is performed -on all files for which the entire expression is true (@pxref{Print File -Name}). +contains no actions other than @samp{-prune}, @samp{-print} is +performed on all files for which the entire expression is true +(@pxref{Print File Name}). Options take effect immediately, rather than being evaluated for each file when their place in the expression is reached. Therefore, for clarity, it is best to place them at the beginning of the expression. Many of the primaries take arguments, which immediately follow them in -the next command line argument to @code{find}. Some arguments are file -names, patterns, or other strings; others are numbers. Numeric +the next command line argument to @code{find}. Some arguments are +file names, patterns, or other strings; others are numbers. Numeric arguments can be specified as @table @code @@ -302,8 +305,8 @@ @chapter Finding Files By default, @code{find} prints to the standard output the names of the -files that match the given criteria. @xref{Actions}, for how to get more -information about the matching files. +files that match the given criteria. @xref{Actions}, for how to get +more information about the matching files. @menu @@ -323,14 +326,15 @@ @node Name @section Name -Here are ways to search for files whose name matches a certain pattern. -@xref{Shell Pattern Matching}, for a description of the @var{pattern} -arguments to these tests. - -Each of these tests has a case-sensitive version and a case-insensitive -version, whose name begins with @samp{i}. In a case-insensitive -comparison, the patterns @samp{fo*} and @samp{F??} match the file names -@file{Foo}, @samp{FOO}, @samp{foo}, @samp{fOo}, etc. +Here are ways to search for files whose name matches a certain +pattern. @xref{Shell Pattern Matching}, for a description of the +@var{pattern} arguments to these tests. + +Each of these tests has a case-sensitive version and a +case-insensitive version, whose name begins with @samp{i}. In a +case-insensitive comparison, the patterns @samp{fo*} and @samp{F??} +match the file names @file{Foo}, @samp{FOO}, @samp{foo}, @samp{fOo}, +etc. @menu * Base Name Patterns:: @@ -344,11 +348,11 @@ @deffn Test -name pattern @deffnx Test -iname pattern -True if the base of the file name (the path with the leading directories -removed) matches shell pattern @var{pattern}. For @samp{-iname}, the -match is case-insensitive. To ignore a whole directory tree, use -@samp{-prune} (@pxref{Directories}). As an example, to find Texinfo -source files in @file{/usr/local/doc}: +True if the base of the file name (the path with the leading +directories removed) matches shell pattern @var{pattern}. For +@samp{-iname}, the match is case-insensitive. To ignore a whole +directory tree, use @samp{-prune} (@pxref{Directories}). As an +example, to find Texinfo source files in @file{/usr/local/doc}: @example find /usr/local/doc -name '*.texi' @@ -358,9 +362,9 @@ Notice that the wildcard must be enclosed in quotes in order to protect it from expansion by the shell. -Patterns for @samp{-name} and @samp{-iname} will match a filename with -a leading @samp{.}. For example the command @samp{find /tmp -name -\*bar} will match the file @file{/tmp/.foobar}. +Patterns for @samp{-name} and @samp{-iname} will match a file name +with a leading @samp{.}. For example the command @samp{find /tmp +-name \*bar} will match the file @file{/tmp/.foobar}. @node Full Name Patterns @@ -373,25 +377,26 @@ For @samp{-iwholename}, the match is case-insensitive. To ignore a whole directory tree, use @samp{-prune} rather than checking every file in the tree (@pxref{Directories}). The ``entire file name'' as -used by find starts with the starting-point specified on the command -line, and is not converted to an absolute pathname, so for example -@code{cd /; find tmp -wholename /tmp} will never match anything. +used by @code{find} starts with the starting-point specified on the +command line, and is not converted to an absolute pathname, so for +example @code{cd /; find tmp -wholename /tmp} will never match +anything. @end deffn @deffn Test -path pattern @deffnx Test -ipath pattern -These tests are deprecated, but work as for @samp{-wholename} and @samp{-iwholename}, -respectively. The @samp{-ipath} test is a GNU extension, but @samp{-path} is also -provided by HP-UX @code{find}. +These tests are deprecated, but work as for @samp{-wholename} and +@samp{-iwholename}, respectively. The @samp{-ipath} test is a GNU +extension, but @samp{-path} is also provided by HP-UX @code{find}. @end deffn @deffn Test -regex expr @deffnx Test -iregex expr True if the entire file name matches regular expression @var{expr}. -This is a match on the whole path, not a search. For example, to match -a file named @file{./fubar3}, you can use the regular expression -@samp{.*bar.} or @samp{.*b.*3}, but not @samp{f.*r3}. @xref{Regexps, , -Syntax of Regular Expressions, emacs, The GNU Emacs Manual}, for a +This is a match on the whole path, not a search. For example, to +match a file named @file{./fubar3}, you can use the regular expression +@samp{.*bar.} or @samp{.*b.*3}, but not @samp{f.*r3}. @xref{Regexps, +, Syntax of Regular Expressions, emacs, The GNU Emacs Manual}, for a description of the syntax of regular expressions. For @samp{-iregex}, the match is case-insensitive. @end deffn @@ -402,9 +407,9 @@ To search for files by name without having to actually scan the directories on the disk (which can be slow), you can use the @code{locate} program. For each shell pattern you give it, -@code{locate} searches one or more databases of file names and displays -the file names that contain the pattern. @xref{Shell Pattern Matching}, -for details about shell patterns. +@code{locate} searches one or more databases of file names and +displays the file names that contain the pattern. @xref{Shell Pattern +Matching}, for details about shell patterns. If a pattern is a plain string---it contains no metacharacters---@code{locate} displays all file names in the database @@ -413,10 +418,10 @@ pattern exactly. As a result, patterns that contain metacharacters should usually begin with a @samp{*}, and will most often end with one as well. The exceptions are patterns that are intended to explicitly -match the beginning or end of a file name. +match the beginning or end of a file name. If you only want @code{locate} to match against the last component of -the filenames (the ``base name'' of the files) you can use the +the file names (the ``base name'' of the files) you can use the @samp{--basename} option. The opposite behaviour is the default, but can be selected explicitly by using the option @samp{--wholename}. @@ -442,8 +447,8 @@ the databases are updated, and the directories for which they contain entries. -Here is how to select which file name databases @code{locate} searches. -The default is system-dependent. +Here is how to select which file name databases @code{locate} +searches. The default is system-dependent. @table @code @item --database=@var{path} @@ -463,9 +468,9 @@ contain the following special characters, which are known as @dfn{wildcards} or @dfn{metacharacters}. -You must quote patterns that contain metacharacters to prevent the shell -from expanding them itself. Double and single quotes both work; so does -escaping with a backslash. +You must quote patterns that contain metacharacters to prevent the +shell from expanding them itself. Double and single quotes both work; +so does escaping with a backslash. @table @code @item * @@ -476,13 +481,13 @@ @item [@var{string}] Matches exactly one character that is a member of the string -@var{string}. This is called a @dfn{character class}. As a shorthand, -@var{string} may contain ranges, which consist of two characters with a -dash between them. For example, the class @samp{[a-z0-9_]} matches a -lowercase letter, a number, or an underscore. You can negate a class by -placing a @samp{!} or @samp{^} immediately after the opening bracket. -Thus, @samp{[^A-Z@@]} matches any character except an uppercase letter -or an at sign. +@var{string}. This is called a @dfn{character class}. As a +shorthand, @var{string} may contain ranges, which consist of two +characters with a dash between them. For example, the class +@samp{[a-z0-9_]} matches a lowercase letter, a number, or an +underscore. You can negate a class by placing a @samp{!} or @samp{^} +immediately after the opening bracket. Thus, @samp{[^A-Z@@]} matches +any character except an uppercase letter or an at sign. @item \ Removes the special meaning of the character that follows it. This @@ -490,16 +495,16 @@ @end table In the @code{find} tests that do shell pattern matching (@samp{-name}, -@samp{-wholename}, etc.), wildcards in the pattern will match a @samp{.} -at the beginning of a file name. This is also the case for +@samp{-wholename}, etc.), wildcards in the pattern will match a +@samp{.} at the beginning of a file name. This is also the case for @code{locate}. Thus, @samp{find -name '*macs'} will match a file named @file{.emacs}, as will @samp{locate '*macs'}. Slash characters have no special significance in the shell pattern -matching that @code{find} and @code{locate} do, unlike in the shell, in -which wildcards do not match them. Therefore, a pattern @samp{foo*bar} -can match a file name @samp{foo3/bar}, and a pattern @samp{./sr*sc} can -match a file name @samp{./src/misc}. +matching that @code{find} and @code{locate} do, unlike in the shell, +in which wildcards do not match them. Therefore, a pattern +@samp{foo*bar} can match a file name @samp{foo3/bar}, and a pattern +@samp{./sr*sc} can match a file name @samp{./src/misc}. If you want to locate some files with the @samp{locate} command but don't need to see the full list you can use the @samp{--limit} option @@ -512,8 +517,8 @@ There are two ways that files can be linked together. @dfn{Symbolic links} are a special type of file whose contents are a portion of the name of another file. @dfn{Hard links} are multiple directory entries -for one file; the file names all have the same index node (@dfn{inode}) -number on the disk. +for one file; the file names all have the same index node +(@dfn{inode}) number on the disk. @menu * Symbolic Links:: @@ -539,7 +544,7 @@ examine that, too). If you would prefer @code{find} to dereference the links and examine the file that each link points to, specify the @samp{-L} option to @code{find}. You can explicitly specify the -default behaviour by using the @samp{-P} option. The @samp{-H} +default behaviour by using the @samp{-P} option. The @samp{-H} option is a half-way-between option which ensures that any symbolic links listed on the command line are dereferenced, but other symbolic links are not. @@ -547,11 +552,11 @@ Symbolic links are different to ``hard links'' in the sense that you need permissions upon the linked-to file in order to be able to dereference the link. This can mean that even if you specify the -@samp{-L} option, find may not be able to determine the properties of -the file that the link points to (because you don't have sufficient -permissions). In this situation, @samp{find} uses the properties of -the link itself. This also occurs if a symbolic link exists but -points to a file that is missing. +@samp{-L} option, @code{find} may not be able to determine the +properties of the file that the link points to (because you don't have +sufficient permissions). In this situation, @code{find} uses the +properties of the link itself. This also occurs if a symbolic link +exists but points to a file that is missing. The options controlling the behaviour of @code{find} with respect to links are as follows :- @@ -560,24 +565,24 @@ @item -P @code{find} does not dereference symbolic links at all. This is the default behaviour. This option must be specified before any of the -path names on the command line. +file names on the command line. @item -H @code{find} does not dereference symbolic links (except in the case of file names on the command line, which are dereferenced). If a symbolic link cannot be dereferenced, the information for the symbolic link itself is used. This option must be specified before any of the -path names on the command line. +file names on the command line. @item -L @code{find} dereferences symbolic links where possible, and where this is not possible it uses the properties of the symbolic link itself. -This option must be specified before any of the path names on the +This option must be specified before any of the file names on the command line. Use of this option also implies the same behaviour as -the @samp{-noleaf} option. If you later use the @samp{-H} or +the @samp{-noleaf} option. If you later use the @samp{-H} or @samp{-P} options, this does not turn off @samp{-noleaf}. @item -follow This option forms part of the ``expression'' and must be specified -after the path names, but it is otherwise equivalent to @samp{-L}. +after the file names, but it is otherwise equivalent to @samp{-L}. @end table The following differences in behavior occur when the @samp{-L} option @@ -597,8 +602,8 @@ Implies @samp{-noleaf} (@pxref{Directories}). @end itemize -If the @samp{-L} option or the @samp{-H} option is used, -the filenames used as arguments to @samp{-newer}, @samp{-anewer}, and +If the @samp{-L} option or the @samp{-H} option is used, +the file names used as arguments to @samp{-newer}, @samp{-anewer}, and @samp{-cnewer} are dereferenced and the timestamp from the pointed-to file is used instead (if possible -- otherwise the timestamp from the symbolic link is used). @@ -609,8 +614,8 @@ @var{pattern}. For @samp{-ilname}, the match is case-insensitive. @xref{Shell Pattern Matching}, for details about the @var{pattern} argument. If the @samp{-L} option is in effect, this test will always -fail for symbolic links unless they are broken. So, to list any -symbolic links to @file{sysdep.c} in the current directory and its +return false for symbolic links unless they are broken. So, to list +any symbolic links to @file{sysdep.c} in the current directory and its subdirectories, you can do: @example @@ -641,10 +646,10 @@ are used to support the @code{ftok()} library function. You can learn a file's inode number and the number of links to it by -running @samp{ls -li} or @samp{find -ls}. +running @samp{ls -li} or @samp{find -ls}. You can search for hard links to inode number NUM by using @samp{-inum -NUM}. If there are any file system mount points below the directory +NUM}. If there are any filesystem mount points below the directory where you are starting the search, use the @samp{-xdev} option unless you are also using the @samp{-L} option. Using @samp{-xdev} this saves needless searching, since hard links to a file must be on the @@ -661,12 +666,13 @@ also work, though these are rarely useful. @end deffn -You can also search for files that have a certain number of links, with -@samp{-links}. Directories normally have at least two hard links; their -@file{.} entry is the second one. If they have subdirectories, each of -those also has a hard link called @file{..} to its parent directory. -The @file{.} and @file{..} directory entries are not normally searched -unless they are mentioned on the @code{find} command line. +You can also search for files that have a certain number of links, +with @samp{-links}. Directories normally have at least two hard +links; their @file{.} entry is the second one. If they have +subdirectories, each of those also has a hard link called @file{..} to +its parent directory. The @file{.} and @file{..} directory entries +are not normally searched unless they are mentioned on the @code{find} +command line. @deffn Test -links n File has @var{n} hard links. @@ -683,8 +689,8 @@ @node Time @section Time -Each file has three time stamps, which record the last time that certain -operations were performed on the file: +Each file has three time stamps, which record the last time that +certain operations were performed on the file: @enumerate @item @@ -698,7 +704,7 @@ There is no timestamp that indicates when a file was @emph{created}. You can search for files whose time stamps are within a certain age -range, or compare them to other time stamps. +range, or compare them to other time stamps. @menu * Age Ranges:: @@ -725,10 +731,10 @@ @deffnx Test -cmin n @deffnx Test -mmin n True if the file was last accessed (or its status changed, or it was -modified) @var{n} minutes ago. These tests provide finer granularity of -measurement than @samp{-atime} et al., but rounding is done in a -similar way. For example, to list files in -@file{/u/bill} that were last read from 2 to 6 minutes ago: +modified) @var{n} minutes ago. These tests provide finer granularity +of measurement than @samp{-atime} et al., but rounding is done in a +similar way. For example, to list files in @file{/u/bill} that were +last read from 2 to 6 minutes ago: @example find /u/bill -amin +2 -amin -6 @@ -736,9 +742,9 @@ @end deffn @deffn Option -daystart -Measure times from the beginning of today rather than from 24 hours ago. -So, to list the regular files in your home directory that were modified -yesterday, do +Measure times from the beginning of today rather than from 24 hours +ago. So, to list the regular files in your home directory that were +modified yesterday, do @example find ~ -daystart -type f -mtime 1 @@ -755,8 +761,8 @@ As an alternative to comparing timestamps to the current time, you can compare them to another file's timestamp. That file's timestamp could -be updated by another program when some event occurs. Or you could set -it to a particular fixed date using the @code{touch} command. For +be updated by another program when some event occurs. Or you could +set it to a particular fixed date using the @code{touch} command. For example, to list files in @file{/usr} modified after February 1 of the current year: @@ -819,10 +825,10 @@ The number can be prefixed with a `+' or a `-'. A plus sign indicates that the test should succeed if the file uses at least @var{n} units -of storage (this is the way I normally use this test) and a minus sign +of storage (a common use of this test) and a minus sign indicates that the test should succeed if the file uses less than -@var{n} units of storage. There is no `=' prefix, because that's the -default anyway. +@var{n} units of storage. There is no `=' prefix, because that's the +default anyway. The size does not count indirect blocks, but it does count blocks in sparse files that are not actually allocated. In other words, it's @@ -834,8 +840,8 @@ @deffn Test -empty True if the file is empty and is either a regular file or a directory. -This might make it a good candidate for deletion. This test is useful -with @samp{-depth} (@pxref{Directories}) and @samp{-delete} +This might help determine good candidates for deletion. This test is +useful with @samp{-depth} (@pxref{Directories}) and @samp{-delete} (@pxref{Single File}). @end deffn @@ -879,8 +885,8 @@ @deffn Test -user uname @deffnx Test -group gname -True if the file is owned by user @var{uname} (belongs to group @var{gname}). -A numeric ID is allowed. +True if the file is owned by user @var{uname} (belongs to group +@var{gname}). A numeric ID is allowed. @end deffn @deffn Test -uid n @@ -893,10 +899,11 @@ @deffn Test -nouser @deffnx Test -nogroup True if no user corresponds to the file's numeric user ID (no group -corresponds to the numeric group ID). These cases usually mean that the -files belonged to users who have since been removed from the system. -You probably should change the ownership of such files to an existing -user or group, using the @code{chown} or @code{chgrp} program. +corresponds to the numeric group ID). These cases usually mean that +the files belonged to users who have since been removed from the +system. You probably should change the ownership of such files to an +existing user or group, using the @code{chown} or @code{chgrp} +program. @end deffn @node Permissions @@ -907,8 +914,8 @@ @deffn Test -perm mode -True if the file's permissions are exactly @var{mode} (which can be -numeric or symbolic). +True if the file's permissions are exactly @var{mode}, which can be +numeric or symbolic. If @var{mode} starts with @samp{-}, true if @emph{all} of the permissions set in @var{mode} are set for the file; @@ -930,7 +937,7 @@ @table @samp @item -perm 664 Match files which have read and write permission for their owner, -and group, but which the rest of the world can read but not write to. +and group, but which the rest of the world can read but not write to. Files which meet these criteria but have other permissions bits set (for example if someone can execute the file) will not be matched. @@ -968,9 +975,9 @@ @node Contents @section Contents -To search for files based on their contents, you can use the @code{grep} -program. For example, to find out which C source files in the current -directory contain the string @samp{thing}, you can do: +To search for files based on their contents, you can use the +@code{grep} program. For example, to find out which C source files in +the current directory contain the string @samp{thing}, you can do: @example grep -l thing *.[ch] @@ -984,12 +991,12 @@ find . -name '*.[ch]' | xargs grep -l thing @end example -The @samp{-l} option causes @code{grep} to print only the names of files -that contain the string, rather than the lines that contain it. The -string argument (@samp{thing}) is actually a regular expression, so it -can contain metacharacters. This method can be refined a little by -using the @samp{-r} option to make @code{xargs} not run @code{grep} if -@code{find} produces no output, and using the @code{find} action +The @samp{-l} option causes @code{grep} to print only the names of +files that contain the string, rather than the lines that contain it. +The string argument (@samp{thing}) is actually a regular expression, +so it can contain metacharacters. This method can be refined a little +by using the @samp{-r} option to make @code{xargs} not run @code{grep} +if @code{find} produces no output, and using the @code{find} action @samp{-print0} and the @code{xargs} option @samp{-0} to avoid misinterpreting files whose names contain spaces: @@ -997,8 +1004,8 @@ find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing @end example -For a fuller treatment of finding files whose contents match a pattern, -see the manual page for @code{grep}. +For a fuller treatment of finding files whose contents match a +pattern, see the manual page for @code{grep}. @node Directories @section Directories @@ -1009,8 +1016,8 @@ @deffn Option -maxdepth levels Descend at most @var{levels} (a non-negative integer) levels of -directories below the command line arguments. @samp{-maxdepth 0} means -only apply the tests and actions to the command line arguments. +directories below the command line arguments. @samp{-maxdepth 0} +means only apply the tests and actions to the command line arguments. @end deffn @deffn Option -mindepth levels @@ -1024,12 +1031,13 @@ this is a good idea when producing lists of files to archive with @code{cpio} or @code{tar}. If a directory does not have write permission for its owner, its contents can still be restored from the -archive since the directory's permissions are restored after its contents. +archive since the directory's permissions are restored after its +contents. @end deffn @deffn Option -d This is a deprecated synonym for @samp{-depth}, for compatibility with -Mac OS X, FreeBSD and OpenBSD. The @samp{-depth} option is a POSIX +Mac OS X, FreeBSD and OpenBSD. The @samp{-depth} option is a POSIX feature, so it is better to use that. @end deffn @@ -1071,25 +1079,25 @@ @deffn Action -quit Exit immediately (with return value zero if no errors have occurred). -No child processes will be left running, but no more paths specified +No child processes will be left running, but no more files specified on the command line will be processed. For example, @code{find /tmp/foo /tmp/bar -print -quit} will print only @samp{/tmp/foo}. -@end deffn +@end deffn @deffn Option -noleaf Do not optimize by assuming that directories contain 2 fewer subdirectories than their hard link count. This option is needed when searching filesystems that do not follow the Unix directory-link convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount -points. Each directory on a normal Unix filesystem has at least 2 hard -links: its name and its @file{.} entry. Additionally, its +points. Each directory on a normal Unix filesystem has at least 2 +hard links: its name and its @file{.} entry. Additionally, its subdirectories (if any) each have a @file{..} entry linked to that directory. When @code{find} is examining a directory, after it has -statted 2 fewer subdirectories than the directory's link count, it knows -that the rest of the entries in the directory are non-directories -(@dfn{leaf} files in the directory tree). If only the files' names need -to be examined, there is no need to stat them; this gives a significant -increase in search speed. +statted 2 fewer subdirectories than the directory's link count, it +knows that the rest of the entries in the directory are +non-directories (@dfn{leaf} files in the directory tree). If only the +files' names need to be examined, there is no need to stat them; this +gives a significant increase in search speed. @end deffn @deffn Option -ignore_readdir_race @@ -1107,7 +1115,8 @@ @end deffn @deffn Option -noignore_readdir_race -This option reverses the effect of the @samp{-ignore_readdir_race} option. +This option reverses the effect of the @samp{-ignore_readdir_race} +option. @end deffn @@ -1116,14 +1125,16 @@ A @dfn{filesystem} is a section of a disk, either on the local host or mounted from a remote host over a network. Searching network -filesystems can be slow, so it is common to make @code{find} avoid them. +filesystems can be slow, so it is common to make @code{find} avoid +them. There are two ways to avoid searching certain filesystems. One way is to tell @code{find} to only search one filesystem: @deffn Option -xdev @deffnx Option -mount -Don't descend directories on other filesystems. These options are synonyms. +Don't descend directories on other filesystems. These options are +synonyms. @end deffn The other way is to check the type of filesystem each file is on, and @@ -1137,11 +1148,11 @@ @example ext2 ext3 proc sysfs ufs 4.2 4.3 nfs tmp mfs S51K S52K @end example -You can use @samp{-printf} with the @samp{%F} directive to see the types -of your filesystems. The @samp{%D} directive shows the device number. -@xref{Print File Information}. @samp{-fstype} is -usually used with @samp{-prune} to avoid searching remote filesystems -(@pxref{Directories}). +You can use @samp{-printf} with the @samp{%F} directive to see the +types of your filesystems. The @samp{%D} directive shows the device +number. @xref{Print File Information}. @samp{-fstype} is usually +used with @samp{-prune} to avoid searching remote filesystems +(@pxref{Directories}). @end deffn @node Combining Primaries With Operators @@ -1179,7 +1190,7 @@ List; both @var{expr1} and @var{expr2} are always evaluated. True if @var{expr2} is true. The value of @var{expr1} is discarded. This operator lets you do multiple independent operations on one traversal, -without depending on whether other operations succeeded. The two +without depending on whether other operations succeeded. The two operations @var{expr1} and @var{expr2} are not always fully independent, since @var{expr1} might have side effects like touching or deleting files, or it might use @samp{-prune} which would also @@ -1187,10 +1198,10 @@ @end table @code{find} searches the directory tree rooted at each file name by -evaluating the expression from left to right, according to the rules of -precedence, until the outcome is known (the left hand side is false for -@samp{-and}, true for @samp{-or}), at which point @code{find} moves on -to the next file name. +evaluating the expression from left to right, according to the rules +of precedence, until the outcome is known (the left hand side is false +for @samp{-and}, true for @samp{-or}), at which point @code{find} +moves on to the next file name. There are two other tests that can be useful in complex expressions: @@ -1209,7 +1220,8 @@ match the criteria you gave in the @code{find} expression. You can print the information either to the standard output or to a file that you name. You can also execute commands that have the file names as -arguments. You can use those commands as further filters to select files. +arguments. You can use those commands as further filters to select +files. @menu * Print File Name:: @@ -1223,12 +1235,12 @@ @section Print File Name @deffn Action -print -True; print the full file name on the standard output, followed by a +True; print the entire file name on the standard output, followed by a newline. @end deffn @deffn Action -fprint file -True; print the full file name into file @var{file}, followed by a +True; print the entire file name into file @var{file}, followed by a newline. If @var{file} does not exist when @code{find} is run, it is created; if it does exist, it is truncated to 0 bytes. The file names @file{/dev/stdout} and @file{/dev/stderr} are handled specially; they @@ -1250,23 +1262,23 @@ @enumerate @item -The inode number of the file. @xref{Hard Links}, for how to find files -based on their inode number. +The inode number of the file. @xref{Hard Links}, for how to find +files based on their inode number. @item the number of blocks in the file. The block counts are of 1K blocks, -unless the environment variable @code{POSIXLY_CORRECT} is set, in which -case 512-byte blocks are used. @xref{Size}, for how to find files based -on their size. +unless the environment variable @code{POSIXLY_CORRECT} is set, in +which case 512-byte blocks are used. @xref{Size}, for how to find +files based on their size. @item The file's type and permissions. The type is shown as a dash for a regular file; for other file types, a letter like for @samp{-type} is used (@pxref{Type}). The permissions are read, write, and execute for -the file's owner, its group, and other users, respectively; a dash means -the permission is not granted. @xref{File Permissions}, for more details -about file permissions. @xref{Permissions}, for how to find files based -on their permissions. +the file's owner, its group, and other users, respectively; a dash +means the permission is not granted. @xref{File Permissions}, for +more details about file permissions. @xref{Permissions}, for how to +find files based on their permissions. @item The number of hard links to the file. @@ -1284,11 +1296,11 @@ The date the file was last modified. @item -The file's name. @samp{-ls} quotes non-printable characters in the file -names using C-like backslash escapes. -This may change soon, as the treatment of unprintable characters is -harmonised for @samp{-ls}, @samp{-fls}, @samp{-print}, @samp{-fprint}, -@samp{-printf} and @samp{-fprintf}. +The file's name. @samp{-ls} quotes non-printable characters in the +file names using C-like backslash escapes. This may change soon, as +the treatment of unprintable characters is harmonised for @samp{-ls}, +@samp{-fls}, @samp{-print}, @samp{-fprint}, @samp{-printf} and +@samp{-fprintf}. @end enumerate @end deffn @@ -1367,9 +1379,9 @@ @samp{%%} is a literal percent sign. A @samp{%} character followed by an unrecognised character (i.e. not a known directive or printf field -width and precision specifier), is discarded (but the unrecognised character -is printed), and a warning message is printed to the standard error output -(because it was probably a typo). +width and precision specifier), is discarded (but the unrecognised +character is printed), and a warning message is printed to the +standard error output (because it was probably a typo). @menu * Name Directives:: @@ -1387,10 +1399,11 @@ @item %p @c supports %-X.Yp File's name (not the absolute path name, but the name of the file as -it was encountered by find - that is, as a relative path from one of -the starting points). +it was encountered by @code{find} - that is, as a relative path from +one of the starting points). @item %f -File's name with any leading directories removed (only the last element). +File's name with any leading directories removed (only the last +element). @c supports %-X.Yf @item %h Leading directories of file's name (all but the last element and the @@ -1429,7 +1442,7 @@ File's numeric user ID. @item %m @c full support, including # and 0. -File's permissions (in octal). If you always want to have a leading +File's permissions (in octal). If you always want to have a leading zero on the number, use the '#' format flag, for example '%#m'. @end table @@ -1438,15 +1451,15 @@ @table @code @item %k -The amount of disk space used for this file in 1K blocks. Since disk space is -allocated in multiples of the filesystem block size this is usually greater -than %s/1024, but it can also be smaller if the file is a sparse file (that is, -it has ``holes''). +The amount of disk space used for this file in 1K blocks. Since disk +space is allocated in multiples of the filesystem block size this is +usually greater than %s/1024, but it can also be smaller if the file +is a sparse file (that is, it has ``holes''). @item %b -The amount of disk space used for this file in 512-byte blocks. Since disk -space is allocated in multiples of the filesystem block size this is usually -greater than %s/1024, but it can also be smaller if the file is a sparse file -(that is, it has ``holes''). +The amount of disk space used for this file in 512-byte blocks. Since +disk space is allocated in multiples of the filesystem block size this +is usually greater than %s/1024, but it can also be smaller if the +file is a sparse file (that is, it has ``holes''). @item %s File's size in bytes. @end table @@ -1472,11 +1485,11 @@ File's inode number (in decimal). @item %n Number of hard links to file. -@item %y -Type of the file as used with @samp{-type}. If the file is a symbolic +@item %y +Type of the file as used with @samp{-type}. If the file is a symbolic link, @samp{l} will be printed. @item %Y -Type of the file as used with @samp{-type}. If the file is a symbolic +Type of the file as used with @samp{-type}. If the file is a symbolic link, it is dereferenced. If the file is a broken symbolic link, @samp{N} is printed. @@ -1494,22 +1507,23 @@ @table @code @item %a -File's last access time in the format returned by the C @code{ctime} function. +File's last access time in the format returned by the C @code{ctime} +function. @item %A@var{k} File's last access time in the format specified by @var{k} -(@pxref{Time Formats}). +(@pxref{Time Formats}). @item %c -File's last status change time in the format returned by the C @code{ctime} -function. +File's last status change time in the format returned by the C +@code{ctime} function. @item %C@var{k} File's last status change time in the format specified by @var{k} (@pxref{Time Formats}). @item %t -File's last modification time in the format returned by the C @code{ctime} -function. +File's last modification time in the format returned by the C +@code{ctime} function. @item %T@var{k} -File's last modification time in the format specified by @var{k} -(@pxref{Time Formats}). +File's last modification time in the format specified by @var{k} +(@pxref{Time Formats}). @end table @node Time Formats @@ -1589,7 +1603,7 @@ @subsubsection Combined Time Formats The following format directives print combinations of time and date -components. +components. @table @code @item r @@ -1616,7 +1630,7 @@ The @samp{%m} and @samp{%d} directives support the @samp{#}, @samp{0} and @samp{+} flags, but the other directives do not, even if they print numbers. Numeric directives that do not support these flags -include +include @samp{G}, @samp{U}, @@ -1649,16 +1663,17 @@ Here is how to run a command on one file at a time. @deffn Action -execdir command ; -Execute @var{command}; true if 0 status is returned. @code{find} takes -all arguments after @samp{-exec} to be part of the command until an -argument consisting of @samp{;} is reached. It replaces the string +Execute @var{command}; true if zero status is returned. @code{find} +takes all arguments after @samp{-exec} to be part of the command until +an argument consisting of @samp{;} is reached. It replaces the string @samp{@{@}} by the current file name being processed everywhere it occurs in the command. Both of these constructions need to be escaped -(with a @samp{\}) or quoted to protect them from expansion by the shell. -The command is executed in the directory in which @code{find} was run. +(with a @samp{\}) or quoted to protect them from expansion by the +shell. The command is executed in the directory in which @code{find} +was run. -For example, to compare each C header file in the current directory with -the file @file{/tmp/master}: +For example, to compare each C header file in the current directory +with the file @file{/tmp/master}: @example find . -name '*.h' -execdir diff -u '@{@}' /tmp/master ';' @@ -1690,7 +1705,7 @@ the time it takes to start up the command each time. The @samp{-execdir} and @samp{-exec} actions have variants that build -command lines containing as many matched files as possible. +command lines containing as many matched files as possible. @deffn Action -execdir command @{@} + This works as for @samp{-execdir command ;}, except that the @@ -1722,7 +1737,8 @@ loops). Another, but less secure, way to run a command on more than one file -at once, is to use the @code{xargs} command, which is invoked like this: +at once, is to use the @code{xargs} command, which is invoked like +this: @example xargs @r{[}@var{option}@dots{}@r{]} @r{[}@var{command} @r{[}@var{initial-arguments}@r{]}@r{]} @@ -1735,23 +1751,23 @@ @var{initial-arguments} followed by arguments read from standard input. Blank lines on the standard input are ignored. -Instead of blank-delimited names, it is safer to use @samp{find -print0} -or @samp{find -fprint0} and process the output by giving the @samp{-0} -or @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU -@code{cpio}, or @code{perl}. The @code{locate} command also has a +Instead of blank-delimited names, it is safer to use @samp{find +-print0} or @samp{find -fprint0} and process the output by giving the +@samp{-0} or @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, +GNU @code{cpio}, or @code{perl}. The @code{locate} command also has a @samp{-0} or @samp{--null} option which does the same thing. -You can use shell command substitution (backquotes) to process a list of -arguments, like this: +You can use shell command substitution (backquotes) to process a list +of arguments, like this: @example grep -l sprintf `find $HOME -name '*.c' -print` @end example However, that method produces an error if the length of the @samp{.c} -file names exceeds the operating system's command-line length limit. -@code{xargs} avoids that problem by running the command as many times as -necessary without exceeding the limit: +file names exceeds the operating system's command line length limit. +@code{xargs} avoids that problem by running the command as many times +as necessary without exceeding the limit: @example find $HOME -name '*.c' -print | xargs grep -l sprintf @@ -1766,7 +1782,7 @@ lines and executing them, unless one of the commands exits with a status of 255 (this will cause xargs to issue an error message and stop) or it reads a line contains the end of file string specified -with the @samp{--eof} option. +with the @samp{--eof} option. @menu * Unsafe File Name Handling:: @@ -1780,25 +1796,26 @@ @subsubsection Unsafe File Name Handling Because file names can contain quotes, backslashes, blank characters, -and even newlines, it is not safe to process them using @code{xargs} in its -default mode of operation. But since most files' names do not contain -blanks, this problem occurs only infrequently. If you are only -searching through files that you know have safe names, then you need not -be concerned about it. +and even newlines, it is not safe to process them using @code{xargs} +in its default mode of operation. But since most files' names do not +contain blanks, this problem occurs only infrequently. If you are +only searching through files that you know have safe names, then you +need not be concerned about it. @c This example is adapted from: @c From: pfalstad@stone.Princeton.EDU (Paul John Falstad) @c Newsgroups: comp.unix.shell @c Subject: Re: Beware xargs security holes @c Date: 16 Oct 90 19:12:06 GMT -@c -In many applications, if @code{xargs} botches processing a file because -its name contains special characters, some data might be lost. The -importance of this problem depends on the importance of the data and -whether anyone notices the loss soon enough to correct it. However, -here is an extreme example of the problems that using blank-delimited -names can cause. If the following command is run daily from -@code{cron}, then any user can remove any file on the system: +@c +In many applications, if @code{xargs} botches processing a file +because its name contains special characters, some data might be lost. +The importance of this problem depends on the importance of the data +and whether anyone notices the loss soon enough to correct it. +However, here is an extreme example of the problems that using +blank-delimited names can cause. If the following command is run +daily from @code{cron}, then any user can remove any file on the +system: @example find / -name '#*' -atime +7 -print | xargs rm @@ -1815,8 +1832,8 @@ and then @code{cron} would delete @file{/vmunix}, if it ran @code{xargs} with @file{/} as its current directory. -To delete other files, for example @file{/u/joeuser/.plan}, you could do -this: +To delete other files, for example @file{/u/joeuser/.plan}, you could +do this: @example eg$ mkdir '# @@ -1836,13 +1853,13 @@ @subsubsection Safe File Name Handling Here is how to make @code{find} output file names so that they can be -used by other programs without being mangled or misinterpreted. You can -process file names generated this way by giving the @samp{-0} or +used by other programs without being mangled or misinterpreted. You +can process file names generated this way by giving the @samp{-0} or @samp{--null} option to GNU @code{xargs}, GNU @code{tar}, GNU @code{cpio}, or @code{perl}. @deffn Action -print0 -True; print the full file name on the standard output, followed by a +True; print the entire file name on the standard output, followed by a null character. @end deffn @@ -1890,12 +1907,12 @@ @table @samp @item -print0 @itemx -fprint0 -Always print the exact filename, unchanged, even if the output is +Always print the exact file name, unchanged, even if the output is going to a terminal. @item -ok @itemx -okdir -Always print the exact filename, unchanged. This will probably change -in a future release. +Always print the exact file name, unchanged. This will probably +change in a future release. @item -ls @itemx -fls Unusual characters are always escaped. White space, backslash, and @@ -1910,30 +1927,30 @@ Otherwise, the result depends on which directive is in use: @table @asis -@item %D, %F, %H, %Y, %y +@item %D, %F, %H, %Y, %y These expand to values which are not under control of files' ownwers, and so are printed as-is. @item %a, %b, %c, %d, %g, %G, %i, %k, %m, %M, %n, %s, %t, %u, %U -These have values which are under the control of files' ownwers but which -cannot be used to send arbitrary data to the terminal, and so these -are printed as-is. -@item %f, %h, %l, %p, %P +These have values which are under the control of files' ownwers but +which cannot be used to send arbitrary data to the terminal, and so +these are printed as-is. +@item %f, %h, %l, %p, %P The output of these directives is quoted if the output is going to a terminal. -This quoting is performed in the same way as for GNU @code{ls}. -This is not the same quoting mechanism as the one used for @samp{-ls} and -@samp{fls}. If you are able to decide what format to use for the output -of @code{find} then it is normally better to use @samp{\0} as a terminator -than to use newline, as file names can contain white space and newline -characters. -@end table +This quoting is performed in the same way as for GNU @code{ls}. This +is not the same quoting mechanism as the one used for @samp{-ls} and +@samp{fls}. If you are able to decide what format to use for the +output of @code{find} then it is normally better to use @samp{\0} as a +terminator than to use newline, as file names can contain white space +and newline characters. +@end table @item -print @itemx -fprint -Quoting is handled in the same way as for the @samp{%p} directive -of @samp{-printf} and @samp{-fprintf}. If you are using @code{find} in -a script or in a situation where the matched files might have -arbitrary names, you should consider using @samp{-print0} instead of +Quoting is handled in the same way as for the @samp{%p} directive of +@samp{-printf} and @samp{-fprintf}. If you are using @code{find} in a +script or in a situation where the matched files might have arbitrary +names, you should consider using @samp{-print0} instead of @samp{-print}. @end table @@ -1948,17 +1965,18 @@ @node Limiting Command Size @subsubsection Limiting Command Size -@code{xargs} gives you control over how many arguments it passes to the -command each time it executes it. By default, it uses up to +@code{xargs} gives you control over how many arguments it passes to +the command each time it executes it. By default, it uses up to @code{ARG_MAX} - 2k, or 128k, whichever is smaller, characters per -command. It uses as many lines and arguments as fit within that limit. -The following options modify those values. +command. It uses as many lines and arguments as fit within that +limit. The following options modify those values. @table @code @item --no-run-if-empty @itemx -r If the standard input does not contain any nonblanks, do not run the -command. By default, the command is run once even if there is no input. +command. By default, the command is run once even if there is no +input. @item --max-lines@r{[}=@var{max-lines}@r{]} @itemx -L@r{[}@var{max-lines}@r{]} @@ -1966,7 +1984,7 @@ Use at most @var{max-lines} nonblank input lines per command line; @var{max-lines} defaults to 1 if omitted. Trailing blanks cause an input line to be logically continued on the next input line, for the -purpose of counting the lines. Implies @samp{-x}. The preferred +purpose of counting the lines. Implies @samp{-x}. The preferred name for this option is @samp{-L} as this is specified by POSIX. This option should be compatible with @samp{-I} but currently it is not. @@ -1974,13 +1992,13 @@ @itemx -n @var{max-args} Use at most @var{max-args} arguments per command line. Fewer than @var{max-args} arguments will be used if the size (see the @samp{-s} -option) is exceeded, unless the @samp{-x} option is given, in which case -@code{xargs} will exit. +option) is exceeded, unless the @samp{-x} option is given, in which +case @code{xargs} will exit. @item --max-chars=@var{max-chars} @itemx -s @var{max-chars} Use at most @var{max-chars} characters per command line, including the -command and initial arguments and the terminating nulls at the ends of +command initial arguments and the terminating nulls at the ends of the argument strings. If you specify a value for this option which is too large or small, a warning message is printed and the appropriate upper or lower limit is used instead. @@ -1990,8 +2008,8 @@ Run up to @var{max-procs} processes at a time; the default is 1. If @var{max-procs} is 0, @code{xargs} will run as many processes as possible at a time. Use the @samp{-n}, @samp{-s}, or @samp{-L} option -with @samp{-P}; otherwise chances are that the command will be run only -once. +with @samp{-P}; otherwise chances are that the command will be run +only once. @end table @node Interspersing File Names @@ -2010,7 +2028,7 @@ terminate arguments; instead, the input is split at newlines only. If @var{replace-str} is omitted, it defaults to @samp{@{@}} (like for @samp{find -exec}). Implies @samp{-x} and @samp{-l 1}. As an -example, to sort each file the @file{bills} directory, leaving the +example, to sort each file in the @file{bills} directory, leaving the output in that file name with @file{.sorted} appended, you could do: @example @@ -2047,10 +2065,11 @@ file. @end deffn -When processing multiple files with a single command, to query the user -you give @code{xargs} the following option. When using this option, you -might find it useful to control the number of files processed per -invocation of the command (@pxref{Limiting Command Size}). +When processing multiple files with a single command, to query the +user you give @code{xargs} the following option. When using this +option, you might find it useful to control the number of files +processed per invocation of the command (@pxref{Limiting Command +Size}). @table @code @item --interactive @@ -2075,11 +2094,11 @@ @section Adding Tests You can test for file attributes that none of the @code{find} builtin -tests check. To do this, use @code{xargs} to run a program that filters -a list of files printed by @code{find}. If possible, use @code{find} -builtin tests to pare down the list, so the program run by @code{xargs} -has less work to do. The tests builtin to @code{find} will likely run -faster than tests that other programs perform. +tests check. To do this, use @code{xargs} to run a program that +filters a list of files printed by @code{find}. If possible, use +@code{find} builtin tests to pare down the list, so the program run by +@code{xargs} has less work to do. The tests builtin to @code{find} +will likely run faster than tests that other programs perform. For reasons of efficiency it is often useful to limit the number of times an external program has to be run. For this reason, it is often @@ -2091,7 +2110,7 @@ executable. @example -find /usr/local -type f -perm /a=x | xargs file | +find /usr/local -type f -perm /a=x | xargs file | grep 'not stripped' | cut -d: -f1 @end example @@ -2114,10 +2133,10 @@ special attribute and make it exit with a true (zero) or false (non-zero) status. It is a good idea to place such a special test @emph{after} the builtin tests, because it starts a new process which -could be avoided if a builtin test evaluates to false. +could be avoided if a builtin test evaluates to false. -Here is a shell script called @code{unstripped} that checks whether its -argument is an unstripped binary file: +Here is a shell script called @code{unstripped} that checks whether +its argument is an unstripped binary file: @example #! /bin/sh @@ -2125,7 +2144,7 @@ @end example -This script relies on the fact that the shell exits with the status of +This script relies on the shell exiting with the status of the last command in the pipeline, in this case @code{grep}. The @code{grep} command exits with a true status if it found any matches, false if not. Here is an example of using the script (assuming it is @@ -2139,12 +2158,11 @@ @end example - @node Common Tasks, Databases, Actions, Top @chapter Common Tasks -The sections that follow contain some extended examples that both give a -good idea of the power of these programs, and show you how to solve +The sections that follow contain some extended examples that both give +a good idea of the power of these programs, and show you how to solve common real-world problems. @menu @@ -2159,10 +2177,10 @@ @node Viewing And Editing @section Viewing And Editing -To view a list of files that meet certain criteria, simply run your file -viewing program with the file names as arguments. Shells substitute a -command enclosed in backquotes with its output, so the whole command -looks like this: +To view a list of files that meet certain criteria, simply run your +file viewing program with the file names as arguments. Shells +substitute a command enclosed in backquotes with its output, so the +whole command looks like this: @example less `find /usr/include -name '*.h' | xargs grep -l mode_t` @@ -2191,21 +2209,21 @@ @node Archiving @section Archiving -You can pass a list of files produced by @code{find} to a file archiving -program. GNU @code{tar} and @code{cpio} can both read lists of file -names from the standard input---either delimited by nulls (the safe way) -or by blanks (the lazy, risky default way). To use null-delimited -names, give them the @samp{--null} option. You can store a file archive -in a file, write it on a tape, or send it over a network to extract on -another machine. - -One common use of @code{find} to archive files is to send a list of the -files in a directory tree to @code{cpio}. Use @samp{-depth} so if a -directory does not have write permission for its owner, its contents can -still be restored from the archive since the directory's permissions are -restored after its contents. Here is an example of doing this using -@code{cpio}; you could use a more complex @code{find} expression to -archive only certain files. +You can pass a list of files produced by @code{find} to a file +archiving program. GNU @code{tar} and @code{cpio} can both read lists +of file names from the standard input---either delimited by nulls (the +safe way) or by blanks (the lazy, risky default way). To use +null-delimited names, give them the @samp{--null} option. You can +store a file archive in a file, write it on a tape, or send it over a +network to extract on another machine. + +One common use of @code{find} to archive files is to send a list of +the files in a directory tree to @code{cpio}. Use @samp{-depth} so if +a directory does not have write permission for its owner, its contents +can still be restored from the archive since the directory's +permissions are restored after its contents. Here is an example of +doing this using @code{cpio}; you could use a more complex @code{find} +expression to archive only certain files. @example find . -depth -print0 | @@ -2241,9 +2259,9 @@ @section Cleaning Up @c Idea from Jim Meyering. -This section gives examples of removing unwanted files in various situations. -Here is a command to remove the CVS backup files created when an update -requires a merge: +This section gives examples of removing unwanted files in various +situations. Here is a command to remove the CVS backup files created +when an update requires a merge: @example find . -name '.#*' -print0 | xargs -0r rm -f @@ -2256,16 +2274,16 @@ @end example @c Idea from Franc,ois Pinard. -You can run this command to clean out your clutter in @file{/tmp}. You -might place it in the file your shell runs when you log out +You can run this command to clean out your clutter in @file{/tmp}. +You might place it in the file your shell runs when you log out (@file{.bash_logout}, @file{.logout}, or @file{.zlogout}, depending on which shell you use). @example -find /tmp -depth -user "$LOGNAME" -type f -delete +find /tmp -depth -user "$LOGNAME" -type f -delete @end example -If your @code{find} command removes directories, you may find that +If your @code{find} command removes directories, you may find that you get a spurious error message when @code{find} tries to recurse into a directory that has now been removed. Using the @samp{-depth} option will normally resolve this problem. @@ -2274,8 +2292,8 @@ To remove old Emacs backup and auto-save files, you can use a command like the following. It is especially important in this case to use null-terminated file names because Emacs packages like the VM mailer -often create temporary file names with spaces in them, like @file{#reply -to David J. MacKenzie<1>#}. +often create temporary file names with spaces in them, like +@file{#reply to David J. MacKenzie<1>#}. @example find ~ \( -name '*~' -o -name '#*#' \) -print0 | @@ -2290,10 +2308,10 @@ find /tmp /var/tmp -depth -mindepth 1 -type d -empty -delete @end example -The second @code{find} command above uses @samp{-depth} so it cleans out -empty directories depth-first, hoping that the parents become empty and -can be removed too. It uses @samp{-mindepth} to avoid removing -@file{/tmp} itself if it becomes totally empty. +The second @code{find} command above uses @samp{-depth} so it cleans +out empty directories depth-first, hoping that the parents become +empty and can be removed too. It uses @samp{-mindepth} to avoid +removing @file{/tmp} itself if it becomes totally empty. @node Strange File Names @section Strange File Names @@ -2304,19 +2322,20 @@ @c Subject: Unix - Frequently Asked Questions (2/7) [Frequent posting] @c Subject: How do I remove a file with funny characters in the filename ? @c Date: Thu Mar 18 17:16:55 EST 1993 -@code{find} can help you remove or rename a file with strange characters -in its name. People are sometimes stymied by files whose names contain -characters such as spaces, tabs, control characters, or characters with -the high bit set. The simplest way to remove such files is: +@code{find} can help you remove or rename a file with strange +characters in its name. People are sometimes stymied by files whose +names contain characters such as spaces, tabs, control characters, or +characters with the high bit set. The simplest way to remove such +files is: @example rm -i @var{some*pattern*that*matches*the*problem*file} @end example @code{rm} asks you whether to remove each file matching the given -pattern. If you are using an old shell, this approach might not work if -the file name contains a character with the high bit set; the shell may -strip it off. A more reliable way is: +pattern. If you are using an old shell, this approach might not work +if the file name contains a character with the high bit set; the shell +may strip it off. A more reliable way is: @example find . -maxdepth 1 @var{tests} -okdir rm '@{@}' \; @@ -2324,26 +2343,26 @@ @noindent where @var{tests} uniquely identify the file. The @samp{-maxdepth 1} -option prevents @code{find} from wasting time searching for the file in -any subdirectories; if there are no subdirectories, you may omit it. A -good way to uniquely identify the problem file is to figure out its -inode number; use +option prevents @code{find} from wasting time searching for the file +in any subdirectories; if there are no subdirectories, you may omit +it. A good way to uniquely identify the problem file is to figure out +its inode number; use @example ls -i @end example -Suppose you have a file whose name contains control characters, and you -have found that its inode number is 12345. This command prompts you for -whether to remove it: +Suppose you have a file whose name contains control characters, and +you have found that its inode number is 12345. This command prompts +you for whether to remove it: @example find . -maxdepth 1 -inum 12345 -okdir rm -f '@{@}' \; @end example -If you don't want to be asked, perhaps because the file name may contain -a strange character sequence that will mess up your screen when printed, -then use @samp{-execdir} instead of @samp{-okdir}. +If you don't want to be asked, perhaps because the file name may +contain a strange character sequence that will mess up your screen +when printed, then use @samp{-execdir} instead of @samp{-okdir}. If you want to rename the file instead, you can use @code{mv} instead of @code{rm}: @@ -2355,9 +2374,10 @@ @node Fixing Permissions @section Fixing Permissions -Suppose you want to make sure that everyone can write to the directories in a -certain directory tree. Here is a way to find directories lacking either -user or group write permission (or both), and fix their permissions: +Suppose you want to make sure that everyone can write to the +directories in a certain directory tree. Here is a way to find +directories lacking either user or group write permission (or both), +and fix their permissions: @example find . -type d -not -perm -ug=w | xargs chmod ug+w @@ -2390,8 +2410,8 @@ cat allexec @end example -@code{find} has only to make one scan through the directory tree (which -is one of the most time consuming parts of its work). +@code{find} has only to make one scan through the directory tree +(which is one of the most time consuming parts of its work). @node Databases, File Permissions, Common Tasks, Top @chapter File Name Databases @@ -2426,9 +2446,10 @@ running the @code{updatedb} program, typically nightly. In networked environments, it often makes sense to build a database at -the root of each filesystem, containing the entries for that filesystem. -@code{updatedb} is then run for each filesystem on the fileserver where -that filesystem is on a local disk, to prevent thrashing the network. +the root of each filesystem, containing the entries for that +filesystem. @code{updatedb} is then run for each filesystem on the +fileserver where that filesystem is on a local disk, to prevent +thrashing the network. @xref{Invoking updatedb}, for the description of the options to @code{updatedb}, which specify @@ -2441,13 +2462,13 @@ The file name databases contain lists of files that were in particular directory trees when the databases were last updated. The file name database format changed starting with GNU @code{locate} version 4.0 to -allow machines with different byte orderings to share the databases. The -new GNU @code{locate} can read both the old and new database formats. -However, old versions of @code{locate} and @code{find} produce incorrect -results if given a new-format database. +allow machines with different byte orderings to share the databases. +The new GNU @code{locate} can read both the old and new database +formats. However, old versions of @code{locate} and @code{find} +produce incorrect results if given a new-format database. If you run @samp{locate --statistics}, the resulting summary indicates -the type of each locate database. +the type of each @code{locate} database. @menu @@ -2460,32 +2481,33 @@ @subsection New Database Format @code{updatedb} runs a program called @code{frcode} to -@dfn{front-compress} the list of file names, which reduces the database -size by a factor of 4 to 5. Front-compression (also known as +@dfn{front-compress} the list of file names, which reduces the +database size by a factor of 4 to 5. Front-compression (also known as incremental encoding) works as follows. The database entries are a sorted list (case-insensitively, for users' -convenience). Since the list is sorted, each entry is likely to share a -prefix (initial string) with the previous entry. Each database entry -begins with an offset-differential count byte, which is the additional -number of characters of prefix of the preceding entry to use beyond the -number that the preceding entry is using of its predecessor. (The -counts can be negative.) Following the count is a null-terminated ASCII -remainder---the part of the name that follows the shared prefix. - -If the offset-differential count is larger than can be stored in a byte -(+/-127), the byte has the value 0x80 and the count follows in a 2-byte -word, with the high byte first (network byte order). +convenience). Since the list is sorted, each entry is likely to share +a prefix (initial string) with the previous entry. Each database +entry begins with an offset-differential count byte, which is the +additional number of characters of prefix of the preceding entry to +use beyond the number that the preceding entry is using of its +predecessor. (The counts can be negative.) Following the count is a +null-terminated ASCII remainder---the part of the name that follows +the shared prefix. + +If the offset-differential count is larger than can be stored in a +byte (+/-127), the byte has the value 0x80 and the count follows in a +2-byte word, with the high byte first (network byte order). Every database begins with a dummy entry for a file called @file{LOCATE02}, which @code{locate} checks for to ensure that the -database file has the correct format; it ignores the entry in doing the -search. +database file has the correct format; it ignores the entry in doing +the search. -Databases can not be concatenated together, even if the first (dummy) +Databases cannot be concatenated together, even if the first (dummy) entry is trimmed from all but the first database. This is because the -offset-differential count in the first entry of the second and following -databases will be wrong. +offset-differential count in the first entry of the second and +following databases will be wrong. In the output of @samp{locate --statistics}, the new database format is referred to as @samp{LOCATE02}. @@ -2529,45 +2551,46 @@ @subsection Old Database Format The old database format is used by Unix @code{locate} and @code{find} -programs and earlier releases of the GNU ones. @code{updatedb} produces -this format if given the @samp{--old-format} option. +programs and earlier releases of the GNU ones. @code{updatedb} +produces this format if given the @samp{--old-format} option. @code{updatedb} runs programs called @code{bigram} and @code{code} to produce old-format databases. The old format differs from the new one in the following ways. Instead of each entry starting with an -offset-differential count byte and ending with a null, byte values from -0 through 28 indicate offset-differential counts from -14 through 14. -The byte value indicating that a long offset-differential count follows -is 0x1e (30), not 0x80. The long counts are stored in host byte order, -which is not necessarily network byte order, and host integer word size, -which is usually 4 bytes. They also represent a count 14 less than -their value. The database lines have no termination byte; the start of -the next line is indicated by its first byte having a value <= 30. +offset-differential count byte and ending with a null, byte values +from 0 through 28 indicate offset-differential counts from -14 through +14. The byte value indicating that a long offset-differential count +follows is 0x1e (30), not 0x80. The long counts are stored in host +byte order, which is not necessarily network byte order, and host +integer word size, which is usually 4 bytes. They also represent a +count 14 less than their value. The database lines have no +termination byte; the start of the next line is indicated by its first +byte having a value <= 30. In addition, instead of starting with a dummy entry, the old database format starts with a 256 byte table containing the 128 most common -bigrams in the file list. A bigram is a pair of adjacent bytes. Bytes -in the database that have the high bit set are indexes (with the high -bit cleared) into the bigram table. The bigram and offset-differential -count coding makes these databases 20-25% smaller than the new format, -but makes them not 8-bit clean. Any byte in a file name that is in the -ranges used for the special codes is replaced in the database by a -question mark, which not coincidentally is the shell wildcard to match a -single character. - -The old format therefore can not faithfully store entries with non-ASCII -characters. It therefore should not be used in internationalized -environments. +bigrams in the file list. A bigram is a pair of adjacent bytes. +Bytes in the database that have the high bit set are indexes (with the +high bit cleared) into the bigram table. The bigram and +offset-differential count coding makes these databases 20-25% smaller +than the new format, but makes them not 8-bit clean. Any byte in a +file name that is in the ranges used for the special codes is replaced +in the database by a question mark, which not coincidentally is the +shell wildcard to match a single character. + +The old format therefore cannot faithfully store entries with +non-ASCII characters. It therefore should not be used in +internationalized environments. The output of @samp{locate --statistics} will give an incorrect count -of the number of filenames containing newlines or high-bit characters +of the number of file names containing newlines or high-bit characters for old-format databases. @node Newline Handling @section Newline Handling -Within the database, filenames are terminated with a null character. -This is the case for both the old and the new format. +Within the database, file names are terminated with a null character. +This is the case for both the old and the new format. When the new database format is being used, the compression technique used to generate the database though relies on the ability to sort the @@ -2576,17 +2599,17 @@ If the system's sort command allows its input list of files to be separated with null characters via the @samp{-z} option, this option is used and therefore @code{updatedb} and @code{locate} will both -correctly handle filenames containing newlines. If the @code{sort} +correctly handle file names containing newlines. If the @code{sort} command lacks support for this, the list of files is delimited with -the newline character, meaning that parts of filenames containing +the newline character, meaning that parts of file names containing newlines will be incorrectly sorted. This can result in both incorrect matches and incorrect failures to match. -On the other hand, if you are using the old database format, filenames -with embedded newlines are not correctly handled. There is no +On the other hand, if you are using the old database format, file +names with embedded newlines are not correctly handled. There is no technical limitation which enforces this, it's just that the -@code{bigram} program has no been updated to support lists of -filenames separated by nulls. +@code{bigram} program has not been updated to support lists of file +names separated by nulls. So, if you are using the new database format (this is the default) and your system uses GNU @code{find}, newlines will be correctly handled @@ -2630,14 +2653,14 @@ describing the files we wish to search for. The first part of the expression is recognised by the fact that it begins with @samp{-}, @samp{(}, @samp{)}, @samp{,}, or @samp{!}. Any arguments after it are -the rest of the expression. If no paths are given, the current +the rest of the expression. If no files are given, the current directory is used. If no expression is given, the expression @samp{-print} is used. -@code{find} exits with status 0 if all files are processed successfully, -greater than 0 if errors occur. +@code{find} exits with status zero if all files are processed +successfully, greater than 0 if errors occur. -Three options can precede the list of path names. They determine the +Three options can precede the list of files. They determine the way that symbolic links are handled. @table @code @@ -2648,7 +2671,7 @@ Always follow symbolic links, except in the case of the @samp{-xtype} predicate. @item -H -Follow symbolic links specified in the list of paths to search, or +Follow symbolic links specified in the list of files to search, or which are otherwise specified on the command line. @end table @@ -2663,12 +2686,11 @@ missing, @samp{-print} is assumed. - @code{find} also recognizes two options for administrative use: @table @code @item --help -Print a summary of the command-line argument format and exit. +Print a summary of the command line argument format and exit. @item --version Print the version number of @code{find} and exit. @end table @@ -2711,7 +2733,7 @@ @item Use of the @samp{-ipath} option which is deprecated; please use @samp{-iwholename} instead. -@item +@item Specifying an option (for example @samp{-mindepth}) after a non-option (for example @samp{-type} or @samp{-print}) on the command line. @end itemize @@ -2741,21 +2763,21 @@ @table @code @item --all @itemx -A -Print only names which match all non-option arguments, not those matching -one or more non-option arguments. +Print only names which match all non-option arguments, not those +matching one or more non-option arguments. @item --basename @itemx -b The specified pattern is matched against just the last component of -the name of the file in the locate database. This last component is -also called the ``base name''. For example, the base name of -@file{/tmp/mystuff/foo.old.c} is @file{foo.old.c}. If the pattern -contains metacharacters, it must match the base name exactly. If not, -it must match part of the base name. +the name of the file in the @code{locate} database. This last +component is also called the ``base name''. For example, the base +name of @file{/tmp/mystuff/foo.old.c} is @file{foo.old.c}. If the +pattern contains metacharacters, it must match the base name exactly. +If not, it must match part of the base name. @item --count @itemx -c -Instead of printing the matched filenames, just print the total +Instead of printing the matched file names, just print the total number of matches we found, unless @samp{--print} (@samp{-p}) is also present. @@ -2823,28 +2845,30 @@ @itemx -0 Results are separated with the ASCII NUL character rather than the newline character. To get the full benefit of the use of this option, -use the new locate database format (that is the default anyway). +use the new @code{locate} database format (that is the default +anyway). @item --print @itemx -p -Print search results when they normally would not, because of the presence -of @samp{--statistics} (@samp{-S}) or @samp{--count} (@samp{-c}). +Print search results when they normally would not, because of the +presence of @samp{--statistics} (@samp{-S}) or @samp{--count} +(@samp{-c}). @item --wholename @itemx -w The specified pattern is matched against the whole name of the file in -the locate database. If the pattern contains metacharacters, it must -match exactly. If not, it must match part of the whole file name. -This is the default behaviour. +the @code{locate} database. If the pattern contains metacharacters, +it must match exactly. If not, it must match part of the whole file +name. This is the default behaviour. @item --regex @itemx -r Instead of using substring or shell glob matching, the pattern specified on the command line is understood to be a POSIX extended -regular expression. Filenames from the locate database which match -the specified regular expression are printed (or counted). If the -@samp{-i} flag is also given, matching is case-insensitive. Matches -are performed against the whole path name, and so by default a +regular expression. File names from the @code{locate} database which +match the specified regular expression are printed (or counted). If +the @samp{-i} flag is also given, matching is case-insensitive. +Matches are performed against the whole path name, and so by default a pathname will be matched if any part of it matches the specified regular expression. The regular expression may use @samp{^} or @samp{$} to anchor a match at the beginning or end of a pathname. @@ -2856,8 +2880,8 @@ @item --statistics @itemx -S -Print some summary information for each locate database. No search is -performed unless non-option arguments are given. +Print some summary information for each @code{locate} database. No +search is performed unless non-option arguments are given. @item --help Print a summary of the options to @code{locate} and exit. @@ -2898,16 +2922,15 @@ slashes. @item --prunefs='@var{path}@dots{}' -File systems to omit from the database, which would otherwise be included. -Note that files are pruned when a file system is reached; -Any file system mounted under an undesired file system will be -ignored. -The environment variable @code{PRUNEFS} also sets this value. -Default is @file{nfs NFS proc}. +Filesystems to omit from the database, which would otherwise be +included. Note that files are pruned when a filesystem is reached; +Any filesystem mounted under an undesired filesystem will be ignored. +The environment variable @code{PRUNEFS} also sets this value. Default +is @file{nfs NFS proc}. @item --output=@var{dbfile} -The database file to build. -Default is system-dependent, but typically @file{/usr/local/var/locatedb}. +The database file to build. Default is system-dependent, but +typically @file{/usr/local/var/locatedb}. @item --localuser=@var{user} The user to search the non-network directories as, using @code{su}. @@ -2915,19 +2938,19 @@ You can also use the environment variable @code{LOCALUSER} to set this user. @item --netuser=@var{user} -The user to search network directories as, using @code{su}. -Default is @code{daemon}. -You can also use the environment variable @code{NETUSER} to set this user. +The user to search network directories as, using @code{su}. Default +is @code{daemon}. You can also use the environment variable +@code{NETUSER} to set this user. @item --old-format -Generate a locate database in the old format, for compatibility with -versions of @code{locate} other than GNU @code{locate}. Using this -option means that @code{locate} will not be able to properly handle -non-ASCII characters in filenames (that is, filenames containing -characters which have the eighth bit set, such as many of the -characters from the ISO-8859-1 character set). +Generate a @code{locate} database in the old format, for compatibility +with versions of @code{locate} other than GNU @code{locate}. Using +this option means that @code{locate} will not be able to properly +handle non-ASCII characters in file names (that is, file names +containing characters which have the eighth bit set, such as many of +the characters from the ISO-8859-1 character set). @item --help -Print a summary of the command-line argument format and exit. +Print a summary of the command line argument format and exit. @item --version Print the version number of @code{updatedb} and exit. @end table @@ -2960,21 +2983,21 @@ @table @code @item --arg-file@r{=@var{inputfile}} -@itemx -a @r{=@var{inputfile}} +@itemx -a o@r{@var{inputfile}} Read names from the file @var{inputfile} instead of standard input. @item --null @itemx -0 -Input filenames are terminated by a null character instead of by +Input file names are terminated by a null character instead of by whitespace, and the quotes and backslash are not special (every character is taken literally). Disables the end of file string, which is treated like any other argument. @item --eof@r{[}=@var{eof-str}@r{]} @itemx -e@r{[}@var{eof-str}@r{]} -Set the end of file string to @var{eof-str}. If the end of file string -occurs as a line of input, the rest of the input is ignored. If -@var{eof-str} is omitted, there is no end of file string. If this +Set the end of file string to @var{eof-str}. If the end of file +string occurs as a line of input, the rest of the input is ignored. +If @var{eof-str} is omitted, there is no end of file string. If this option is not given, the end of file string defaults to @samp{_}. @item --help @@ -2999,8 +3022,8 @@ @itemx -n @var{max-args} Use at most @var{max-args} arguments per command line. Fewer than @var{max-args} arguments will be used if the size (see the @samp{-s} -option) is exceeded, unless the @samp{-x} option is given, in which case -@code{xargs} will exit. +option) is exceeded, unless the @samp{-x} option is given, in which +case @code{xargs} will exit. @item --interactive @itemx -p @@ -3011,12 +3034,13 @@ @item --no-run-if-empty @itemx -r If the standard input does not contain any nonblanks, do not run the -command. By default, the command is run once even if there is no input. +command. By default, the command is run once even if there is no +input. @item --max-chars=@var{max-chars} @itemx -s @var{max-chars} Use at most @var{max-chars} characters per command line, including the -command and initial arguments and the terminating nulls at the ends of +command, initial arguments and the terminating nulls at the ends of the argument strings. @item --verbose @@ -3044,21 +3068,21 @@ Security considerations are important if you are using @code{find} or @code{xargs} to search for or process files that don't belong to you -or over which other people have control. Security considerations +or which other people have control. Security considerations relating to @code{locate} may also apply if you have files which you -may not want others to see. +do not want others to see. In general, the most severe forms of security problems affecting @code{find} and related programs are where third parties can bring -about a situation where those programs allow them to do something -they would normally not be able to do. This is called @emph{privilege +about a situation where those programs allow them to do something they +would normally not be able to do. This is called @emph{privilege elevation}. This might include deleting files they would not normally be able to delete. It is also common for the system to periodically invoke @code{find} for housekeeping purposes. These invocations of @code{find} are particularly problematic from a security point of view -as these are often invoked by the superuser and search the whole file -system hierarchy. The severity of any associated problem depends on -what the system is going to do with the output of @code{find}. +as these are often invoked by the superuser and search the whole +filesystem hierarchy. The severity of any associated problem depends +on what the system is going to do with the output of @code{find}. @menu * Levels of Risk:: What is your level of exposure to security problems? @@ -3084,7 +3108,7 @@ @file{/home} or @file{/tmp}). @item Medium Risk -Systems where the actions of other users can create filenames chosen +Systems where the actions of other users can create file names chosen by them, but to which they don't have access while @code{find} is being run. This access might include leaving programs running (shell background jobs, @code{at} or @code{cron} tasks, for example). On @@ -3094,7 +3118,7 @@ @item Low Risk Systems to which untrusted parties do not have access, cannot create -filenames of their own choice (even remotely) and which contain no +file names of their own choice (even remotely) and which contain no security flaws which might enable an untrusted third party to gain access. Most systems do not fall into this category because there are many ways in which external parties can affect the names of files that @@ -3115,7 +3139,7 @@ disastrous, then you should still give serious thought to all the possible security problems, many of which of course will not be discussed here -- this section of the manual is intended to be -informative but not comprehensive or exhaustive. +informative but not comprehensive or exhaustive. If you are responsible for the operation of a system where the consequences of a security problem could be very important, you should @@ -3123,27 +3147,27 @@ @enumerate @item Define a security policy which defines who is allowed to do what -on your system +on your system. @item Seek competent advice on how to enforce your policy, detect breaches of that policy, and take account of any potential problems -that might fall outside the scope of your policy +that might fall outside the scope of your policy. @end enumerate @node Security Considerations for find -@section Security Considerations for find +@section Security Considerations for @code{find} Some of the actions @code{find} might take have a direct effect; these include @code{-exec} and @code{-delete}. However, it is also common to use @code{-print} explicitly or implicitly, and so if -@code{find} produces the wrong list of filenames, that can also be a +@code{find} produces the wrong list of file names, that can also be a security problem; consider the case for example where @code{find} is producing a list of files to be deleted. We normally assume that the @code{find} command line expresses the file selection criteria and actions that the user had in mind -- that -is, the command line is ``trusted'' data. +is, the command line is ``trusted'' data. From a security analysis point of view, the output of @code{find} should be correct; that is, the output should contain only the names @@ -3155,7 +3179,7 @@ by other people, and hence we regard this as ``untrusted'' data. This implies that the @code{find} command line is a filter which converts the untrusted contents of the filesystem into a correct list of output -files. +files. The filesystem will in general change while @code{find} is searching it; in fact, most of the potential security problems with @code{find} @@ -3164,14 +3188,14 @@ Race conditions are a general class of security problem where the relative ordering of actions taken by @code{find} (for example) and something else are important@footnote{This is more or less the -definition of the term ``race condition''} . +definition of the term ``race condition''} . Typically, an attacker might move or rename files or directories in -the hope that an action might be taken against a a file which was not +the hope that an action might be taken against a file which was not normally intended to be affected. Alternatively, this sort of attack might be intended to persuade @code{find} to search part of the filesystem which would not normally be included in the search -(defeating the @code{-prune} action for example). +(defeating the @code{-prune} action for example). @menu * Changing the Current Working Directory:: @@ -3183,8 +3207,8 @@ @node Changing the Current Working Directory @subsection Changing the Current Working Directory -As find searches the file system, it finds subdirectories and then -searches within them by changing its working directory. First, +As @code{find} searches the filesystem, it finds subdirectories and +then searches within them by changing its working directory. First, @code{find} notices a subdirectory. It then decides if that subdirectory meets the criteria for being searched; that is, any @samp{-xdev} or @samp{-prune} expressions are taken into account. The @@ -3194,7 +3218,7 @@ A race condition attack might take the form that once the checks relevant to @samp{-xdev} and @samp{-prune} have been done, an attacker might rename the directory that was being considered, and put in its -place a symbolic link that actually points somewhere else. +place a symbolic link that actually points somewhere else. The idea behind this attack is to fool @code{find} into going into the wrong directory. This would leave @code{find} with a working @@ -3207,9 +3231,9 @@ GNU @code{find} has specific safeguards to prevent this general class of problem. The exact form of these safeguards depends on the -properties of your system. +properties of your system. -@menu +@menu * O_NOFOLLOW:: Safely changing directory using fchdir(). * Systems without O_NOFOLLOW:: Checking for symbolic links after chdir(). * Working with automounters:: These can look like race condition exploits @@ -3217,7 +3241,7 @@ @end menu @node O_NOFOLLOW -@subsubsection O_NOFOLLOW +@subsubsection O_NOFOLLOW If your system supports the O_NOFOLLOW flag @footnote{GNU/Linux (kernel version 2.1.126 and later) and FreeBSD (3.0-CURRENT and later) @@ -3232,7 +3256,7 @@ back on the method which is normally used if O_NOFOLLOW is not supported. -You can tell if your system supports O_NOFOLLOW by running +You can tell if your system supports O_NOFOLLOW by running @example find --version @@ -3245,16 +3269,16 @@ Features enabled: D_TYPE O_NOFOLLOW(enabled) @end example -Here, you can see that I am running a version of find which was built -from the development (CVS) code prior to the release of +Here, you can see that I am running a version of @code{find} which was +built from the development (CVS) code prior to the release of findutils-4.2.18, and that the D_TYPE and O_NOFOLLOW features are present. O_NOFOLLOW is qualified with ``enabled''. This simply means that the current system seems to support O_NOFOLLOW. This check is -needed because it is possible to build find on a system that defines -O_NOFOLLOW and then run it on a system that ignores the O_NOFOLLOW -flag. We try to detect such cases at startup by checking the -operating system and version number; when this happens you will see -``O_NOFOLLOW(disabled)'' instead. +needed because it is possible to build @code{find} on a system that +defines O_NOFOLLOW and then run it on a system that ignores the +O_NOFOLLOW flag. We try to detect such cases at startup by checking +the operating system and version number; when this happens you will +see ``O_NOFOLLOW(disabled)'' instead. @node Systems without O_NOFOLLOW @subsubsection Systems without O_NOFOLLOW @@ -3276,11 +3300,11 @@ Where an automounter is in use it can be the case that the use of the @code{chdir()} system call can itself cause a new filesystem to be mounted at that point. On systems that do not support O_NOFOLLOW, -this will cause @code{find}'s security check to fail. +this will cause @code{find}'s security check to fail. -However, this does not normally represent a security problem (since +However, this does not normally represent a security problem, since the automounter configuration is normally set up by the system -administrator). Therefore, if the @code{chdir()} sanity check fails, +administrator. Therefore, if the @code{chdir()} sanity check fails, @code{find} will check to see if a new filesystem has been mounted at the current directory; if so, @code{find} will issue a warning message and continue. @@ -3299,7 +3323,7 @@ system has a filesystem mounted on an unresponsive NFS server, @code{find} will hang, waiting for the NFS server to respond. Worse, it does this even if the affected mount point is not within the -directory tree that find would have searched anyway. +directory tree that @code{find} would have searched anyway. This is very unfortunate. However, this problem only affects systems that have no support for O_NOFOLLOW. As far as I can tell, it is not @@ -3312,13 +3336,13 @@ @node Race Conditions with -exec @subsection Race Conditions with -exec -The @samp{-exec} action causes another program to be run. It is -passed the name of the file which is being considered at the time. -The invoked program will then - normally - perform some action on that -file. Once again, there is a race condition which can be exploited -here. We shall take as a specific example the command +The @samp{-exec} action causes another program to be run. It passes +to the program the name of the file which is being considered at the +time. The invoked program will then - normally - perform some action +on that file. Once again, there is a race condition which can be +exploited here. We shall take as a specific example the command -@example +@example find /tmp -path /tmp/umsp/passwd -exec /bin/rm @end example @@ -3329,11 +3353,11 @@ @code{/bin/rm} command actually issues the @code{unlink()} system call. Within this time period, an attacker can rename the @file{/tmp/umsp} directory, replacing it with a symbolic link to -@file{/etc}. There is no way for @code{/bin/rm} to determine that it -is working on the same file that @code{find} had in mind. Once the +@file{/etc}. There is no way for @code{/bin/rm} to determine that it +is working on the same file that @code{find} had in mind. Once the symbolic link is in place, the attacker has persuaded @code{find} to cause the deletion of the @file{/etc/passwd} file, which is not the -effect intended by the command which was actually invoked. +effect intended by the command which was actually invoked. One possible defence against this type of attack is to modify the behaviour of @samp{-exec} so that the @code{/bin/rm} command is run @@ -3343,8 +3367,8 @@ this strategy cannot be used as the POSIX standard specifies that the current working directory for commands invoked via @samp{-exec} must be the same as the current working directory from which @code{find} -was invoked. This means that the @samp{-exec} action is inherently -insecure and can't be fixed. +was invoked. This means that the @samp{-exec} action is inherently +insecure and can't be fixed. GNU @code{find} implements a more secure variant of the @samp{-exec} action, @samp{-execdir}. The @samp{-execdir} action @@ -3368,20 +3392,20 @@ The @samp{-print} and @samp{-print0} actions can be used to produce a list of files matching some criteria, which can then be used with some -other command, perhaps with @code{xargs}. Unfortunately, this means +other command, perhaps with @code{xargs}. Unfortunately, this means that there is an unavoidable time gap between @code{find} deciding that one or more files meet its criteria and the relevant command being executed. For this reason, the @samp{-print} and @samp{-print0} actions are just as insecure as @samp{-exec}. -In fact, since the construction +In fact, since the construction @example -find .... -print | xargs .... +find .... -print | xargs .... @end example does not cope correctly with newlines or other ``white space'' in -filenames, and copes poorly with filenames containing quotes, the +file names, and copes poorly with file names containing quotes, the @samp{-print} action is less secure even than @samp{-print0}. @@ -3398,7 +3422,7 @@ However, there are other security issues that exist even if it is not possible for an attacker to have access to the filesystem in real time. Firstly, if it is possible for an attacker to create files with -names of their own choice on the filesystem, then @code{xargs} is +names of their choice on the filesystem, then @code{xargs} is insecure unless the @samp{-0} option is used. If a file with the name @file{/home/someuser/foo/bar\n/etc/passwd} exists (assume that @samp{\n} stands for a newline character), then @code{find ... -print} @@ -3415,8 +3439,8 @@ files, the @file{/etc/passwd} file would be included even if this was not the intent of the person running find. There are circumstances in which an attacker can use this to their advantage. The same -consideration applies to filenames containing ordinary spaces rather -than newlines, except that of course the list of filenames will no +consideration applies to file names containing ordinary spaces rather +than newlines, except that of course the list of file names will no longer contain an ``extra'' newline. This problem is an unavoidable consequence of the default behaviour of @@ -3424,8 +3448,8 @@ The only ways to avoid this problem are either to avoid all use of @code{xargs} in favour for example of @samp{find -exec} or (where available) @samp{find -execdir}, or to use the @samp{-0} option, which -ensures that @code{xargs} considers filenames to be separated by ASCII -NUL characters rather than whitespace. However, useful though this +ensures that @code{xargs} considers file names to be separated by +ASCII NUL characters rather than whitespace. However, useful as this option is, the POSIX standard does not make it mandatory. @comment node-name, next, previous, up @@ -3435,7 +3459,7 @@ It is fairly unusual for the output of @code{locate} to be fed into another command. However, if this were to be done, this would raise the same set of security issues as the use of @samp{find ... -print}. -Although the problems relating to whitespace in filenames can be +Although the problems relating to whitespace in file names can be resolved by using @code{locate}'s @samp{-0} option, this still leaves the race condition problems associated with @samp{find ... -print0}. There is no way to avoid these problems in the case of @code{locate}. @@ -3450,23 +3474,24 @@ @table @asis @item Informational use only -Uses where the programs are used to prepare lists of filenames upon which no further action will ever be taken. +Uses where the programs are used to prepare lists of file names upon +which no further action will ever be taken. -@item -delete -Use of the @samp{-delete} action to delete files which meet -specified criteria +@item @samp{-delete} +Use of the @samp{-delete} action with @code{find} to delete files +which meet specified criteria -@item -execdir -Use of the @samp{-execdir} action where the @env{PATH} +@item @samp{-execdir} +Use of the @samp{-execdir} action with @code{find} where the @env{PATH} environment variable contains directories which contain only trusted -programs. +programs. @end table @comment node-name, next, previous, up @node Error Messages, Primary Index, Security Considerations, Top @chapter Error Messages -This section describes some of the error messages you might get from +This section describes some of the error messages sometimes made by @code{find}, @code{xargs}, or @code{locate}, explains them and in some cases provides advice as to what you should do about this. @@ -3474,8 +3499,8 @@ features translated error messages for many languages. For this reason where possible we try to make the error messages produced by the programs self-explanatory. This approach avoids asking people to -figure out which English-language error message the test they actually -saw might correspond to. Error messages which are self-explanatory +figure out which English-language error message +corresponds to a test. Error messages which are self-explanatory will not normally be described or discussed in this document. For those messages which are discussed in this document, only the English-language version of the message will be listed. @@ -3488,7 +3513,7 @@ @end menu @node Error Messages From find, Error Messages From xargs, , Error Messages -@section Error Messages From find +@section Error Messages From @code{find} @table @samp @item invalid predicate `-foo' @@ -3523,9 +3548,9 @@ @item /path/foo changed during execution of find (old device number 12345, new device number 6789, filesystem type is ) [ref XXX] This message is issued when @code{find} changes directory and ends up somewhere it didn't expect to be. This happens in one of two -circumstances. Firstly this happens when ``automount'' does its thing -on a system where @code{find} doesn't know how to determine what the -current set of mounted filesystems is +circumstances. Firstly, this happens when ``automount'' does its +thing on a system where @code{find} doesn't know how to determine what +the current set of mounted filesystems is Secondly, this can happen when the device number of a directory appears to change during a change of current directory, but @@ -3544,8 +3569,8 @@ is different to the inode number that it obtained when it examined the directory some time previously. This normally means that while @code{find} has been deep in a directory hierarchy doing something -time consuming, somebody has moved the one of the parent directories -to another location in the same filesystem. This may have been done +time consuming, somebody has moved one of the parent directories to +another location in the same filesystem. This may have been done maliciously, or may not. In any case, @code{find} stops at this point in order to avoid traversing parts of the filesystem that it wasn't intended to. You can use @code{ls -li} or @code{find /path -inum @@ -3560,7 +3585,7 @@ @code{configure}, but which doesn't work properly. @item cannot fork -This normally happens if you use the @code{-exec} action or a +This normally happens if you use the @code{-exec} action or something similar (@code{-ok} and so forth) but the system has run out of free process slots. This is either because the system is very busy and the system has reached its maximum process limit, or because you @@ -3574,24 +3599,27 @@ @end table - @node Error Messages From xargs, Error Messages From locate, Error Messages From find, Error Messages @section Error Messages From xargs @table @samp @item environment is too large for exec -This message means that you have so many environment variables set -(or such large values for them) that there is no room within the -system-imposed limits on program command-line argument length to -invoke any program. I'm sure you did this deliberately. Please try -unsetting some environment variables, or exiting the current shell. +This message means that you have so many environment variables set (or +such large values for them) that there is no room within the +system-imposed limits on program command line argument length to +invoke any program. This is an unlikely situation and is more likely +result of an attempt to test the limits of @code{xargs}, or break it. +Please try unsetting some environment variables, or exiting the +current shell. @item can not fit single argument within argument list size limit You are using the @samp{-i} option and @code{xargs} doesn't have -enough space to build a command line because it has read in a really +enough space to build a command line because it has read a really large item and it doesn't fit. You can probably work around this problem with the @samp{-s} option, but the default size is pretty -large. You must be trying pretty hard to break @code{xargs}. +large. This is a rare situation and is more likely an attempt to test +the limits of @code{xargs}, or break it. Otherwise, you will need to +try to shorten the problematic argument or not use @code{xargs}. @item cannot fork See the description of the similar message for @code{find}. @@ -3607,15 +3635,16 @@ @end table @node Error Messages From locate, Error Messages From updatedb, Error Messages From xargs, Error Messages -@section Error Messages From locate +@section Error Messages From @code{locate} @table @samp @item warning: database `/usr/local/var/locatedb' is more than 8 days old The @code{locate} program relies on a database which is periodically built by the @code{updatedb} program. That hasn't happened in a long time. To fix this problem, run @code{updatedb} manually. This can -often happen on systems that are generally not left on, so the periodic -``cron'' task which normally does this doesn't get a chance to run. +often happen on systems that are generally not left on, so the +periodic ``cron'' task which normally does this doesn't get a chance +to run. @item locate database `/usr/local/var/locatedb' is corrupt or invalid This should not happen. Re-run @code{updatedb}. If that works, but @@ -3633,9 +3662,9 @@ @section Error Messages From updatedb The @code{updatedb} program (and the programs it invokes) do issue -error messages, but none of them seem to me to be candidates for -guidance. If you are having a problem understanding one of these, ask -for help on @email{bug-findutils@@gnu.org}. +error messages, but none seem to be candidates for guidance. If +you are having a problem understanding one of these, ask for help on +@email{bug-findutils@@gnu.org}. @node Primary Index, , Error Messages, Top @unnumbered @code{find} Primary Index