Difference between revisions 508016 and 508017 on knwiki

{{other uses}}
{{unreferenced|date=September 2013}}
{{lowercase|title=find}} 
In [[Unix-like]] and some other [[operating system]]s, <code>'''find'''</code> is a [[command-line utility]] that [[Search engine (computing)|searches]] through one or more [[directory tree]]s of a [[file system]], locates [[Computer file|file]]s based on some [[user (computing)|user]]-specified criteria and applies a user-specified action on each matched file. The possible search criteria include a [[pattern matching|pattern]] to match against the [[file name]] or a time range to match against the modification time or access time of the file. By default, <code>find</code> returns a list of all files below the current [[working directory]].

The related <code>[[locate (Unix)|locate]]</code> programs use a database of indexed files obtained through <code>find</code> (updated at regular intervals, typically by <code>[[cron]]</code> job) to provide a faster method of searching the entire filesystem for files by name.  

== Find syntax ==
{{expand section|date=August 2008}}

<code>find [-H] [-L] [-P] path... [expression]</code>

The three options control how the <code>find</code> command should treat symbolic links. The default behaviour is never to follow symbolic links. This can be explicitly specified using the -P flag. The -L flag will cause the <code>find</code> command to follow symbolic links. The -H flag will only follow symbolic links while processing the command line arguments. These flags are not available with some older versions of <code>find</code>.

At least one path must precede the expression. <code>find</code> is capable of interpreting [[Wildcard character|wildcards]] internally and commands must be constructed carefully in order to control [[Glob (programming)|shell globbing]].

Expression elements are whitespace-separated and evaluated from left to right.  They can contain logical elements such as AND (&#x2011;and or &#x2011;a) and OR (&#x2011;or or &#x2011;o) as well as more complex predicates.

The [[GNU Find Utilities|GNU]] <code>find</code> has a large number of additional features not specified by POSIX.

== POSIX protection from infinite output ==

Real-world filesystems often contain looped structures created through the use of [[hard link|hard]] or [[symbolic link|soft links]].  The [[POSIX|POSIX standard]] requires that
{{Quotation|
The <code>find</code> utility shall detect infinite loops; that is, entering a previously visited
directory that is an ancestor of the last file encountered. When it detects an infinite
loop, <code>find</code> shall write a diagnostic message to standard error and shall either recover
its position in the hierarchy or terminate.
}}
⏎
⏎
==Operators ==
Operators can be used to enhance the expressions of the find command. Operators are listed in order of decreasing precedence:

*'''( expr )''' Force precedence. 
*'''! expr''' True if expr is false. 
*'''-not expr''' Same as ! expr. 
*'''expr1 expr2''' And (implied); expr2 is not evaluated if expr1 is false. 
*'''expr1 -a expr2''' Same as expr1 expr2. 
*'''expr1 -and expr2''' Same as expr1 expr2. 
*'''expr1 -o expr2''' Or; expr2 is not evaluated if expr1 is true. 
*'''expr1 -or expr2''' Same as expr1 -o expr2 but doesn't work as widely (since POSIX doesn't require it). 
*'''expr1  , expr2''' List; both expr1 and expr2 are always evaluated. The value of expr1 is discarded (though its side-effects occur); the value of the list is the value of expr2.  

 find . -name 'fileA_*' -o -name 'fileB_*'

This command searches files whose name has a prefix of "fileA_" or "fileB_" in the current directory.

 find . -name 'foo.cpp' '!' -path '.svn'

This command searches for files with the name "foo.cpp" in all subdirectories of the current directory (current directory itself included) other than ".svn".   We quote the ! so that it's not interpreted by the shell as the history substitution character.

==Type filter explanation==

'''-type''' ''option used to specify search for only file, link or directory.''
Various type filters are supported by find, they are activated using the

 find -type c

configuration switch where c may be any of:
* '''b '''[[Device file|block (buffered) special]]
* '''c '''[[Device file|character (unbuffered special)]]
* '''d [[Directory (computing)|directory]]'''
* '''p '''[[Named pipe|named pipe (FIFO)]]
* '''f [[regular file]]'''
* '''l '''[[symbolic link]]; this is never true if the -L option or the -follow option is in effect, unless the symbolic link is broken. If you want to search for symbolic links when -L is in effect, use -xtype (though that is a GNU extension).
* '''s '''[[Unix domain socket|socket]]
* '''D '''[[Doors (computing)|door (Solaris)]]
(Bold listed configuration switches are most commonly used)

==Examples==
⏎
⏎
===From current directory===
 find . -name 'my*'

This searches in the current directory (represented by the dot character) and below it, for files and directories with names starting with ''my''. The quotes avoid the [[shell (computing)|shell]] expansion — without them the shell would replace ''my*'' with the list of files whose names begin with ''my'' in the current directory. In newer versions of the program, the directory may be omitted, and it will imply the current directory.

===Files only===
 find . -name 'my*' -type f
This limits the results of the above search to only regular files, therefore excluding directories, special files, pipes, symbolic links, etc. ''my*'' is enclosed in single quotes (apostrophes) as otherwise the shell would replace it with the list of  files in the current directory starting with ''my''......

===Commands===
The previous examples created listings of results because, by default, <code>find</code> executes the '-print' action.   (Note that early versions of the <code>find</code> command had no default action at all; therefore the resulting list of files would be discarded, to the bewilderment of users.)  

 find . -name 'my*' -type f -ls
This prints extended file information.

===Search all directories===
 find / -name myfile -type f -print
This searches every file on the computer for a file with the name ''myfile'' and prints it to the screen. It is generally not a good idea to look for data files this way.  This can take a considerable amount of time, so it is best to specify the directory more precisely.  Some operating systems may mount dynamic filesystems that are not congenial to <code>find</code>.   More complex filenames including characters special to the shell may need to be enclosed in single quotes.

===Search all but one directory subtree===
 find / -path excluded_path -prune -o -type f -name myfile -print
This searches every folder on the computer except the subtree ''excluded_path'' (full path including the leading /), for a file with the name ''myfile''.  It will not detect directories, devices, links, doors, or other "special" filetypes.

===Specify a directory===
 find /home/weedly -name 'myfile' -type f -print
This searches for files named ''myfile'' in the ''/home/weedly'' directory, the home directory for userid ''weedly''.  You should always specify the directory to the deepest level you can remember.  The quotes are optional in this example because "myfile" contains no characters special to the shell.

===Search several directories===
 find local /tmp -name mydir -type d -print
This searches for directories named ''mydir'' in the ''local'' subdirectory of the current working directory and the ''/tmp'' directory.

===Ignore errors===
If you're doing this as a user other than root, you might want to ignore permission denied (and any other) errors.  Since errors are printed to [[stderr]], they can be suppressed by redirecting the output to /dev/null.  The following example shows how to do this in the bash shell: 
 find / -name 'myfile' -type f -print 2>/dev/null

If you are a [[C shell|csh]] or [[tcsh]] user, you cannot redirect [[stderr]] without redirecting [[stdout]] as well.  You can use sh to run the <code>find</code> command to get around this:
 sh -c find / -name 'myfile' -type f -print 2>/dev/null

An alternate method when using [[C shell|csh]] or [[tcsh]] is to pipe the output from [[stdout]] and [[stderr]] into a [[grep]] command. This example shows how to suppress lines that contain permission denied errors.
 find . -name 'myfile' |& grep -v 'Permission denied'

===Find any one of differently named files===
 find . \( -name '*jsp' -o -name '*java' \) -type f -ls

The <code>-ls</code> option prints extended information, and the example finds any file whose name ends with either 'jsp' or 'java'. Note that the parentheses are required. Also note that the operator "or" can be abbreviated as "o". The "and" operator is assumed where no operator is given.  In many shells the parentheses must be escaped with a backslash, "\(" and "\)", to prevent them from being interpreted as special shell characters. The <code>-ls</code> option and the <code>-or</code> operator are not available on all versions of <code>find</code>.

===Execute an action===
 find /var/ftp/mp3 -name '*.mp3' -type f -exec chmod 644 {} \;
This command changes the [[File system permissions|permissions]] of all files with a name ending in ''.mp3'' in the directory ''/var/ftp/mp3''. The  action is carried out by specifying the option <code>-exec [[chmod]] 644 {} \;</code> in the command. For every file whose name ends in <code>.mp3</code>, the command <code>chmod 644 {}</code> is executed replacing <code>{}</code> with the name of the file. The semicolon (backslashed to avoid the shell interpreting it as a command separator) indicates the end of the command. Permission <code>644</code>, usually shown as <code>rw-r--r--</code>, gives the file owner full permission to read and write the file, while other users have read-only access. In some shells, the <code>{}</code> must be quoted.  The trailing ";" is customarily quoted with a leading "\", but could just as effectively be enclosed in single quotes.

Note that the command itself should *not* be quoted; otherwise you get error messages like

 find: echo "mv ./3bfn rel071204": No such file or directory

which means that <code>find</code> is trying to run a file called 'echo "mv ./3bfn rel071204"' and failing.

If you will be executing over many results, it is more efficient to pipe the results to the [[xargs]] command instead.  xargs is a more modern implementation, and handles long lists in a more intelligent way.  The print0 option can be used with this.

The following command will ensure that filenames with whitespaces are passed to the executed COMMAND without being split up by the shell.  It looks complicated at first glance, but is widely used.

 find . -print0 | xargs -0 COMMAND

The list of files generated by <code>find</code> (whilst it is being generated) is simultaneously [[Pipe (Unix)|piped]] to xargs, which then executes COMMAND with the files as arguments.  See [[xargs]] for more examples and options.

===Delete files and directories===
'''Caveats''': the -delete action is a GNU extension, and using it turns on -depth.   So, if you are testing a find command with -print instead of -delete in order to figure out what will happen before going for it, you need to use -depth -print.

Delete empty files and directories and print the names
 find /foo -empty -delete -print

Delete empty files
 find /foo -type f -empty -delete

Delete empty directories
 find /foo -type d -empty -delete

Delete files and directories (if empty) named <code>bad</code> 
 find /foo -name bad -empty -delete

'''Warning''': <code>-delete</code> should be used with other operators such as
<code>-empty</code> or <code>-name</code>.

 find /foo -delete  # this deletes '''all''' in /foo

===Search for a string===
This command will search for a string in all files from the /tmp directory and below:
<source lang="bash">
 $ find /tmp =type f -exec grep 'search string' '{}' /dev/null \+
</source>
The <tt>[[/dev/null]]</tt> argument is used to show the name of the file before the text that is found. Without it, only the text found is printed.  An equivalent mechanism is to use the "-H" or "--with-filename" option to grep:
<source lang="bash">
 $ find /tmp -type f -exec grep -H 'search string' '{}' '+' 
</source>
GNU grep can be used on its own to perform this task:

 $ grep -r 'search string' /tmp

Example of search for "LOG" in jsmith's home directory
<source lang="bash" highlight="1">
 $ find ~jsmith -exec grep LOG '{}' /dev/null \; -print
 /home/jsmith/scripts/errpt.sh:cp $LOG $FIXEDLOGNAME
 /home/jsmith/scripts/errpt.sh:cat $LOG
 /home/jsmith/scripts/title:USER=$LOGNAME
</source>
Example of search for the string "ERROR" in all XML files in the current directory and all sub-directories
<source lang="bash">

 $ find . -name "*.xml" -exec grep "ERROR" /dev/null '{}' \+ 
</source>
The double quotes (" ") surrounding the search string and single quotes (<nowiki>' '</nowiki>) surrounding the braces are optional in this example, but needed to allow spaces and some other special characters in the string.  Note with more complex text (notably in most popular shells descended from `sh` and `csh`) single quotes are often the easier choice, since '''double quotes do not prevent all special interpretation'''. Quoting filenames which have English contractions demonstrates how this can get rather complicated, since a string with an apostrophe in it is easier to protect with double quotes.  Example:
<source lang="bash">

 $ find . -name "file-containing-can't" -exec grep "can't" '{}' \; -print
</source>

===Search for all files owned by a user===
 find . -user <userid>

===Search in case insensitive mode===
 find . -iname ''''MyFile'''*'

If the <code>-iname</code> switch is not supported on your system then workaround techniques may be possible such as:

 find . -name '[m'''M''']['''y'''Y][f'''F''']['''i'''I]['''l'''L]['''e'''E]*'

This uses [[Perl]] to build the above command for you (though in general this kind of usage is dangerous, since special characters are not properly quoted before being fed into the standard input of `sh`):

 echo "''''MyFile'''*'" |perl -pe 's/([a-zA-Z])/[\L\1\U\1]/g;s/(.*)/find . -name \1/'|sh

===Search files by size===
Example of searching files with size between 100 kilobytes and 500 kilobytes.
 find . -size +100k -a -size -500k
Example of searching empty files.
 find . -size 0k
Example of searching non-empty files.
 find . -not -size 0k

===Search files by name and size ===
 '''find''' /usr/src {{abbr|-not|the negation of the expression that follows}} {{abbr|\(|the start of a complex expression.}} -name '*,v' {{abbr|-o|a logical or of a complex expression. In this case the complex expression is all files like '*,v' or '.*,v'}} -name '.*,v' {{abbr|\)|the end of a complex expression.}} '{}' \; -print  

This command will search in the /usr/src directory and all sub directories. All files that are of the form '*,v' and '.*,v' are excluded. Important arguments to note are in the [[tooltip]] that is displayed on mouse-over.

<source lang="bash" enclose="div">
for file in `find /opt \( -name error_log -o -name 'access_log' -o -name 'ssl_engine_log' -o -name 'rewrite_log' -o
 -name 'catalina.out' \) -size +300000k -a -size -5000000k`; do 
    cat /dev/null > $file
done
</source>
The units should be one of [bckw], 'b' means 512-byte blocks, 'c' means byte, 'k' means kilobytes and 'w' means 2-byte words. The size does not count indirect blocks, but it does count blocks in sparse files that are not actually allocated.

==Related utilities==
* <code>[[locate (Unix)|locate]]</code> is a Unix search tool that searches through a prebuilt database of files instead of directory trees of a file system. This is faster than <code>find</code> but less accurate because the database may not be up-to-date.
* <code>[[grep]]</code> is a command-line utility for searching plain-text data sets for lines matching a regular expression and by default reporting matching lines on [[standard output]].
* <code>[[tree (Unix)|tree]]</code> is a command-line utility that recursively lists files found in a directory tree, indenting the file names according to their position in the file hierarchy.
* [[GNU Find Utilities]] (also known as findutils) is a [[GNU package]] which contains implementations of the tools <code>find</code> and [[xargs]].
* [[BusyBox]] is a utility that provides several stripped-down Unix tools in a single executable file, intended for embedded operating systems with very limited resources. It also provides a version of <code>find</code>.

==See also==
*[[mdfind]], a similar utility that utilizes metadata for [[Mac OS X]] and [[Darwin (operating system)|Darwin]]
*[[List of Unix programs]]
*[[List of DOS commands]]
*[[List of duplicate file finders]]
*[[Filter (higher-order function)]]
*[[find (command)]], a DOS and Windows command that is very different from UNIX <code>find</code>

==External links==
*{{man|cu|find|SUS|find files}}
*{{man|1|find||search for files in a directory hierarchy}}
*[http://www.gnu.org/software/findutils/manual/html_mono/find.html Official webpage for GNU find]

{{Unix commands}}

[[Category:Searching]]
[[Category:Standard Unix programs]]
[[Category:Unix SUS2008 utilities]]