2.2 Starting points

GNU find searches the directory tree rooted at each given starting-point by evaluating the given expression from left to right, according to the rules of operator precedence, until the outcome is known (the left hand side is false for ‘and’ operations, true for ‘or’), at which point find moves on to the next file name.

If no starting-point is specified, the current directory ‘.’ is assumed.

A double dash ‘--’ could theoretically be used to signal that any remaining arguments are not options, but this does not really work due to the way find determines the end of the list of starting point arguments: it does that by reading until an expression argument comes (which also starts with a ‘-’). Now, if a starting point argument would begin with a ‘-’, then find would treat it as expression argument instead. Thus, to ensure that all start points are taken as such, and especially to prevent that wildcard patterns expanded by the calling shell are not mistakenly treated as expression arguments, it is generally safer to prefix wildcards or dubious path names with either ‘./’, or to use absolute path names starting with ‘/’.

Alternatively, it is generally safe though non-portable to use the GNU option ‘-files0-from’ to pass arbitrary starting points to find.

Option: -files0-from file

Option: -files0-from file

Read the starting points from file instead of getting them on the command line. In contrast to the known limitations of passing starting points via arguments on the command line, namely the limitation of the amount of file names, and the inherent ambiguity of file names clashing with option names, using this option allows to safely pass an arbitrary number of starting points to find.

Using this option and passing starting points on the command line is mutually exclusive, and is therefore not allowed at the same time.

The file argument is mandatory. One can use ‘-files0-from -’ to read the list of starting points from the standard input stream, and e.g. from a pipe. In this case, the actions ‘-ok’ and ‘-okdir’ are not allowed, because they would obviously interfere with reading from standard input in order to get a user confirmation.

The starting points in file have to be separated by ASCII NUL characters. Two consecutive NUL characters, i.e., a starting point with a Zero-length file name is not allowed and will lead to an error diagnostic followed by a non-Zero exit code later.

In the case the given file is empty, find does not process any starting point and therefore will exit immediately after parsing the program arguments. This is unlike the standard invocation where find assumes the current directory as starting point if no path argument is passed.

The processing of the starting points is otherwise as usual, e.g. find will recurse into subdirectories unless otherwise prevented. To process only the starting points, one can additionally pass ‘-maxdepth 0’.

Further notes: if a file is listed more than once in the input file, it is unspecified whether it is visited more than once. If the file is mutated during the operation of find, the result is unspecified as well. Finally, the seek position within the named ‘file’ at the time find exits, be it with ‘-quit’ or in any other way, is also unspecified. By "unspecified" here is meant that it may or may not work or do any specific thing, and that the behavior may change from platform to platform, or from findutils release to release.

Example: Given that another program proggy pre-filters and creates a huge NUL-separated list of files, process those as starting points, and find all regular, empty files among them:

$ proggy | find -files0-from - -maxdepth 0 -type f -empty

The use of ‘-files0-from -’ means to read the names of the starting points from standard input, i.e., from the pipe; and ‘-maxdepth 0’ ensures that only explicitly those entries are examined without recursing into directories (in the case one of the starting points is one).