Starting points (GNU Findutils 4.11.0)

Next: Name, Previous: find Expressions, Up: Finding Files [Contents][Index]

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 ¶

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

Warnings

Warnings
In order to use this option safely, you need to take care about some specific things: Ensure there are no duplicate entries Otherwise, some files may (or may not) be visited more than once. Do not modify the file while `find` is running The effects of any concurrent modification are unspecified. Do not rely on the final seek position in the file There is no guarantee about the final seek position. It may vary between platforms, between findutils release, or even between runs of `find`. Therefore, sharing the same open file between ‘`-files0-from`’ and anything else (including use of ‘`-files0-from`’ in another instance of the `find` program) is unlikely to reliably do what you want. Instead if you need to read from the same file in more than one program, open it separately for each.

In order to use this option safely, you need to take care about some specific things:

Ensure there are no duplicate entries
- Otherwise, some files may (or may not) be visited more than once.
Do not modify the file while find is running
- The effects of any concurrent modification are unspecified.
Do not rely on the final seek position in the file
- There is no guarantee about the final seek position. It may vary between platforms, between findutils release, or even between runs of find.
- Therefore, sharing the same open file between ‘-files0-from’ and anything else (including use of ‘-files0-from’ in another instance of the find program) is unlikely to reliably do what you want. Instead if you need to read from the same file in more than one program, open it separately for each.

Suppose that some program proggy pre-filters and creates a huge NUL-separated list of files, we can 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. Using ‘-maxdepth 0’ ensures that only explicitly those entries are examined without recursing into directories (in the case one of the starting points is one).