Finding Files

GNU Findutils

This file documents the GNU utilities for finding files that match certain criteria and performing various operations on them.

Copyright (C) 1994, 1996, 1998, 2000, 2001, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”

This file documents the GNU utilities for finding files that match certain criteria and performing various actions on them.

This is edition 4.4.0, for find version 4.4.0.

• Introduction: Summary of the tasks this manual describes.
• Finding Files: Finding files that match certain criteria.
• Actions: Doing things to files you have found.
• Databases: Maintaining file name databases.
• File Permissions: How to control access to files.
• Date input formats: Specifying literal times.
• Reference: Summary of how to invoke the programs.
• Common Tasks: Solutions to common real-world problems.
• Worked Examples: Examples demonstrating more complex points.
• Security Considerations: Security issues relating to findutils.
• Error Messages: Explanations of some messages you might see.
• GNU Free Documentation License: Copying and sharing this manual.
• Primary Index: The components of find expressions.

1 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 find, locate, and xargs. Some of the examples in this manual use capabilities specific to the GNU versions of those programs.

GNU find was originally written by Eric Decker, with enhancements by David MacKenzie, Jay Plett, and Tim Wood. GNU xargs was originally written by Mike Rendell, with enhancements by David MacKenzie. GNU locate and its associated utilities were originally written by James Woods, with enhancements by David MacKenzie. The idea for ‘find -print0’ and ‘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!

To report a bug in GNU findutils, please use the form on the Savannah web site at http://savannah.gnu.org/bugs/?group=findutils. Reporting bugs this way means that you will then be able to track progress in fixing the problem.

If you don't have web access, you can also just send mail to the mailing list. The mailing list bug-findutils@gnu.org carries discussion of bugs in findutils, questions and answers about the software and discussion of the development of the programs. To join the list, send email to bug-findutils-request@gnu.org.

Please read any relevant sections of this manual before asking for help on the mailing list. You may also find it helpful to read the NON-BUGS section of the find manual page.

If you ask for help on the mailing list, people will be able to help you much more effectively if you include the following things:

• The version of the software you are running. You can find this out by running ‘locate --version’.
• What you were trying to do
• The exact command line you used
• The exact output you got (if this is very long, try to find a smaller example which exhibits the same problem)
• The output you expected to get

It may also be the case that the bug you are describing has already been fixed, if it is a bug. Please check the most recent findutils releases at ftp://ftp.gnu.org/gnu/findutils and, if possible, the development branch at ftp://alpha.gnu.org/gnu/findutils. If you take the time to check that your bug still exists in current releases, this will greatly help people who want to help you solve your problem. Please also be aware that if you obtained findutils as part of the GNU/Linux 'distribution', the distributions often lag seriously behind findutils releases, even the stable release. Please check the GNU FTP site.

• Scope
• Overview
• find Expressions

1.1 Scope

For brevity, the word 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 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”:

     parser.c
     README
     ./budget/may-94.sc
     fred/.cshrc
     /usr/local/include/termcap.h

A 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:

• have names that contain certain text or match a certain pattern;
• are links to certain files;
• were last used during a certain period of time;
• are within a certain size range;
• are of a certain type (regular file, directory, symbolic link, etc.);
• are owned by a certain user or group;
• have certain access permissions or special mode bits;
• contain text that matches a certain pattern;
• are within a certain depth in the directory tree;
• or some combination of the above.

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:

• view or edit
• store in an archive
• remove or rename
• change access permissions
• classify into groups

This manual describes how to perform each of those tasks, and more.

1.2 Overview

The principal programs used for making lists of files that match given criteria and running commands on them are find, locate, and xargs. An additional command, updatedb, is used by system administrators to create databases for locate to use.

find searches for files in a directory hierarchy and prints information about the files it found. It is run like this:

     find [file...] [expression]

Here is a typical use of find. This example prints the names of all files in the directory tree rooted in /usr/src whose name ends with ‘.c’ and that are larger than 100 Kilobytes.

     find /usr/src -name '*.c' -size +100k -print

Notice that the wildcard must be enclosed in quotes in order to protect it from expansion by the shell.

locate searches special file name databases for file names that match patterns. The system administrator runs the updatedb program to create the databases. locate is run like this:

     locate [option...] pattern...

This example prints the names of all files in the default file name database whose name ends with ‘Makefile’ or ‘makefile’. Which file names are stored in the database depends on how the system administrator ran updatedb.

     locate '*[Mm]akefile'

The name xargs, pronounced EX-args, means “combine arguments.” 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 find. xargs is run like this:

     xargs [option...] [command [initial-arguments]]

The following command searches the files listed in the file file-list and prints all of the lines in them that contain the word ‘typedef’.

     xargs grep typedef < file-list

1.3 find Expressions

The expression that find uses to select files consists of one or more primaries, each of which is a separate command line argument to find. find evaluates the expression each time it processes a file. An expression can contain any of the following types of primaries:

options

affect overall operation rather than the processing of a specific file;

tests

return a true or false value, depending on the file's attributes;

actions

have side effects and return a true or false value; and

operators

connect the other arguments and affect when and whether they are evaluated.

You can omit the operator between two primaries; it defaults to ‘-and’. See Combining Primaries With Operators, for ways to connect primaries into more complex expressions. If the expression contains no actions other than ‘-prune’, ‘-print’ is performed on all files for which the entire expression is true (see 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. There are two exceptions to this; ‘-daystart’ and ‘-follow’ have different effects depending on where in the command line they appear. This can be confusing, so it's best to keep them at the beginning, too.

Many of the primaries take arguments, which immediately follow them in the next command line argument to find. Some arguments are file names, patterns, or other strings; others are numbers. Numeric arguments can be specified as

+n

for greater than n,

-n

for less than n,

n

for exactly n.

2 Finding Files

By default, find prints to the standard output the names of the files that match the given criteria. See Actions, for how to get more information about the matching files.

• Name
• Links
• Time
• Size
• Type
• Owner
• Mode Bits
• Contents
• Directories
• Filesystems
• Combining Primaries With Operators

2.1 Name

Here are ways to search for files whose name matches a certain pattern. See Shell Pattern Matching, for a description of the pattern arguments to these tests.

Each of these tests has a case-sensitive version and a case-insensitive version, whose name begins with ‘i’. In a case-insensitive comparison, the patterns ‘fo*’ and ‘F??’ match the file names Foo, ‘FOO’, ‘foo’, ‘fOo’, etc.

• Base Name Patterns
• Full Name Patterns
• Fast Full Name Search
• Shell Pattern Matching: Wildcards used by these programs.

2.1.1 Base Name Patterns

2.1.2 Full Name Patterns

In the context of the tests ‘-path’, ‘-wholename’, ‘-ipath’ and ‘-wholename’, a “full path” is the name of all the directories traversed from find's start point to the file being tested, followed by the base name of the file itself. These paths are often not absolute paths; for example

     $ cd /tmp
     $ mkdir -p foo/bar/baz
     $ find foo -path foo/bar -print
     foo/bar
     $ find foo -path /tmp/foo/bar -print
     $ find /tmp/foo -path /tmp/foo/bar -print
     /tmp/foo/bar

Notice that the second find command prints nothing, even though /tmp/foo/bar exists and was examined by find.

Unlike file name expansion on the command line, a ‘*’ in the pattern will match both ‘/’ and leading dots in file names:

     $ find .  -path '*f'
     ./quux/bar/baz/f
     $ find .  -path '*/*config'
     ./quux/bar/baz/.config

2.1.3 Fast Full Name Search

To search for files by name without having to actually scan the directories on the disk (which can be slow), you can use the locate program. For each shell pattern you give it, locate searches one or more databases of file names and displays the file names that contain the pattern. See Shell Pattern Matching, for details about shell patterns.

If a pattern is a plain string—it contains no metacharacters—locate displays all file names in the database that contain that string. If a pattern contains metacharacters, locate only displays file names that match the pattern exactly. As a result, patterns that contain metacharacters should usually begin with a ‘*’, 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.

If you only want locate to match against the last component of the file names (the “base name” of the files) you can use the ‘--basename’ option. The opposite behaviour is the default, but can be selected explicitly by using the option ‘--wholename’.

The command

     locate pattern

is almost equivalent to

     find directories -name pattern

where directories are the directories for which the file name databases contain information. The differences are that the locate information might be out of date, and that locate handles wildcards in the pattern slightly differently than find (see Shell Pattern Matching).

The file name databases contain lists of files that were on the system when the databases were last updated. The system administrator can choose the file name of the default database, the frequency with which the databases are updated, and the directories for which they contain entries.

Here is how to select which file name databases locate searches. The default is system-dependent. At the time this document was generated, the default was /usr/local/var/locatedb.

--database=path

-d path

Instead of searching the default file name database, search the file name databases in path, which is a colon-separated list of database file names. You can also use the environment variable LOCATE_PATH to set the list of database files to search. The option overrides the environment variable if both are used.

GNU locate can read file name databases generated by the slocate package. However, these generally contain a list of all the files on the system, and so when using this database, locate will produce output only for files which are accessible to you. See Invoking locate, for a description of the ‘--existing’ option which is used to do this.

The updatedb program can also generate database in a format compatible with slocate. See Invoking updatedb, for a description of its ‘--dbformat’ and ‘--output’ options.

2.1.4 Shell Pattern Matching

find and locate can compare file names, or parts of file names, to shell patterns. A shell pattern is a string that may contain the following special characters, which are known as wildcards or 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.

*

Matches any zero or more characters.

?

Matches any one character.

[string]

Matches exactly one character that is a member of the string string. This is called a character class. As a shorthand, string may contain ranges, which consist of two characters with a dash between them. For example, the class ‘[a-z0-9_]’ matches a lowercase letter, a number, or an underscore. You can negate a class by placing a ‘!’ or ‘^’ immediately after the opening bracket. Thus, ‘[^A-Z@]’ matches any character except an uppercase letter or an at sign.

\

Removes the special meaning of the character that follows it. This works even in character classes.

In the find tests that do shell pattern matching (‘-name’, ‘-wholename’, etc.), wildcards in the pattern will match a ‘.’ at the beginning of a file name. This is also the case for locate. Thus, ‘find -name '*macs'’ will match a file named .emacs, as will ‘locate '*macs'’.

Slash characters have no special significance in the shell pattern matching that find and locate do, unlike in the shell, in which wildcards do not match them. Therefore, a pattern ‘foo*bar’ can match a file name ‘foo3/bar’, and a pattern ‘./sr*sc’ can match a file name ‘./src/misc’.

If you want to locate some files with the ‘locate’ command but don't need to see the full list you can use the ‘--limit’ option to see just a small number of results, or the ‘--count’ option to display only the total number of matches.

2.2 Links

There are two ways that files can be linked together. Symbolic links are a special type of file whose contents are a portion of the name of another file. Hard links are multiple directory entries for one file; the file names all have the same index node (inode) number on the disk.

• Symbolic Links
• Hard Links

2.2.1 Symbolic Links

Symbolic links are names that reference other files. GNU find will handle symbolic links in one of two ways; firstly, it can dereference the links for you - this means that if it comes across a symbolic link, it examines the file that the link points to, in order to see if it matches the criteria you have specified. Secondly, it can check the link itself in case you might be looking for the actual link. If the file that the symbolic link points to is also within the directory hierarchy you are searching with the find command, you may not see a great deal of difference between these two alternatives.

By default, find examines symbolic links themselves when it finds them (and, if it later comes across the linked-to file, it will examine that, too). If you would prefer find to dereference the links and examine the file that each link points to, specify the ‘-L’ option to find. You can explicitly specify the default behaviour by using the ‘-P’ option. The ‘-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.

Symbolic links are different from “hard links” in the sense that you need permission to search the directories in the linked-to file name to dereference the link. This can mean that even if you specify the ‘-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 permission). In this situation, 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 find with respect to links are as follows :-

‘-P’

find does not dereference symbolic links at all. This is the default behaviour. This option must be specified before any of the file names on the command line.

‘-H’

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 file names on the command line.

‘-L’

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 file names on the command line. Use of this option also implies the same behaviour as the ‘-noleaf’ option. If you later use the ‘-H’ or ‘-P’ options, this does not turn off ‘-noleaf’.

‘-follow’

This option forms part of the “expression” and must be specified after the file names, but it is otherwise equivalent to ‘-L’. The ‘-follow’ option affects only those tests which appear after it on the command line. This option is deprecated. Where possible, you should use ‘-L’ instead.

The following differences in behavior occur when the ‘-L’ option is used:

• find follows symbolic links to directories when searching directory trees.
• ‘-lname’ and ‘-ilname’ always return false (unless they happen to match broken symbolic links).
• ‘-type’ reports the types of the files that symbolic links point to. This means that in combination with ‘-L’, ‘-type l’ will be true only for broken symbolic links. To check for symbolic links when ‘-L’ has been specified, use ‘-xtype l’.
• Implies ‘-noleaf’ (see Directories).

If the ‘-L’ option or the ‘-H’ option is used, the file names used as arguments to ‘-newer’, ‘-anewer’, and ‘-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).

2.2.2 Hard Links

Hard links allow more than one name to refer to the same file. To find all the names which refer to the same file as NAME, use ‘-samefile NAME’. If you are not using the ‘-L’ option, you can confine your search to one filesystem using the ‘-xdev’ option. This is useful because hard links cannot point outside a single filesystem, so this can cut down on needless searching.

If the ‘-L’ option is in effect, and NAME is in fact a symbolic link, the symbolic link will be dereferenced. Hence you are searching for other links (hard or symbolic) to the file pointed to by NAME. If ‘-L’ is in effect but NAME is not itself a symbolic link, other symbolic links to the file NAME will be matched.

You can also search for files by inode number. This can occasionally be useful in diagnosing problems with filesystems for example, because fsck tends to print inode numbers. Inode numbers also occasionally turn up in log messages for some types of software, and are used to support the ftok() library function.

You can learn a file's inode number and the number of links to it by running ‘ls -li’ or ‘find -ls’.

You can search for hard links to inode number NUM by using ‘-inum NUM’. If there are any filesystem mount points below the directory where you are starting the search, use the ‘-xdev’ option unless you are also using the ‘-L’ option. Using ‘-xdev’ this saves needless searching, since hard links to a file must be on the same filesystem. See Filesystems.

You can also search for files that have a certain number of links, with ‘-links’. Directories normally have at least two hard links; their . entry is the second one. If they have subdirectories, each of those also has a hard link called .. to its parent directory. The . and .. directory entries are not normally searched unless they are mentioned on the find command line.

2.3 Time

Each file has three time stamps, which record the last time that certain operations were performed on the file:

1. access (read the file's contents)
2. change the status (modify the file or its attributes)
3. modify (change the file's contents)

Some systems also provide a timestamp that indicates when a file was created. For example, the UFS2 fileystem under NetBSD-3.1 records the birth time of each file. This information is also available under other versions of BSD and some versions of Cygwin. However, even on systems which support file birth time, files may exist for which this information was not recorded (for example, UFS1 file systems simply do not contain this information).

You can search for files whose time stamps are within a certain age range, or compare them to other time stamps.

• Age Ranges
• Comparing Timestamps

2.3.1 Age Ranges

These tests are mainly useful with ranges (‘+n’ and ‘-n’).

2.3.2 Comparing Timestamps

There are two ways to list files in /usr modified after February 1 of the current year. One uses ‘-newermt’:

     find /usr -newermt "Feb 1"

The other way of doing this works on the versions of find before 4.3.3:

     touch -t 02010000 /tmp/stamp$$
     find /usr -newer /tmp/stamp$$
     rm -f /tmp/stamp$$

2.4 Size

2.5 Type

2.6 Owner

2.7 File Mode Bits

See File Permissions, for information on how file mode bits are structured and how to specify them.

Four tests determine what users can do with files. These are ‘-readable’, ‘-writable’, ‘-executable’ and ‘-perm’. The first three tests ask the operating system if the current user can perform the relevant operation on a file, while ‘-perm’ just examines the file's mode. The file mode may give a misleading impression of what the user can actually do, because the file may have an access control list, or exist on a read-only filesystem, for example. Of these four tests though, only ‘-perm’ is specified by the POSIX standard.

The ‘-readable’, ‘-writable’ and ‘-executable’ tests are implemented via the access system call. This is implemented within the operating system itself. If the file being considered is on an NFS filesystem, the remote system may allow or forbid read or write operations for reasons of which the NFS client cannot take account. This includes user-ID mapping, either in the general sense or the more restricted sense in which remote superusers are treated by the NFS server as if they are the local user ‘nobody’ on the NFS server.

None of the tests in this section should be used to verify that a user is authorised to perform any operation (on the file being tested or any other file) because of the possibility of a race condition. That is, the situation may change between the test and an action being taken on the basis of the result of that test.

2.8 Contents

To search for files based on their contents, you can use the grep program. For example, to find out which C source files in the current directory contain the string ‘thing’, you can do:

     grep -l thing *.[ch]

If you also want to search for the string in files in subdirectories, you can combine grep with find and xargs, like this:

     find . -name '*.[ch]' | xargs grep -l thing

The ‘-l’ option causes grep to print only the names of files that contain the string, rather than the lines that contain it. The string argument (‘thing’) is actually a regular expression, so it can contain metacharacters. This method can be refined a little by using the ‘-r’ option to make xargs not run grep if find produces no output, and using the find action ‘-print0’ and the xargs option ‘-0’ to avoid misinterpreting files whose names contain spaces:

     find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing

For a fuller treatment of finding files whose contents match a pattern, see the manual page for grep.

2.9 Directories

Here is how to control which directories find searches, and how it searches them. These two options allow you to process a horizontal slice of a directory tree.

2.10 Filesystems

A 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 find avoid them.

There are two ways to avoid searching certain filesystems. One way is to tell find to only search one filesystem:

The other way is to check the type of filesystem each file is on, and not descend directories that are on undesirable filesystem types:

2.11 Combining Primaries With Operators

Operators build a complex expression from tests and actions. The operators are, in order of decreasing precedence:

( expr )

Force precedence. True if expr is true.

! expr

-not expr

True if expr is false. In some shells, it is necessary to protect the ‘!’ from shell interpretation by quoting it.

expr1 expr2

expr1 -a expr2

expr1 -and expr2

And; expr2 is not evaluated if expr1 is false.

expr1 -o expr2

expr1 -or expr2

Or; expr2 is not evaluated if expr1 is true.

expr1 , expr2

List; both expr1 and expr2 are always evaluated. True if expr2 is true. The value of expr1 is discarded. This operator lets you do multiple independent operations on one traversal, without depending on whether other operations succeeded. The two operations expr1 and expr2 are not always fully independent, since expr1 might have side effects like touching or deleting files, or it might use ‘-prune’ which would also affect expr2.

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 ‘-and’, true for ‘-or’), at which point find moves on to the next file name.

There are two other tests that can be useful in complex expressions:

3 Actions

There are several ways you can print information about the files that match the criteria you gave in the 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.

• Print File Name
• Print File Information
• Run Commands
• Delete Files
• Adding Tests

3.1 Print File Name

3.2 Print File Information

• Escapes
• Format Directives
• Time Formats

3.2.1 Escapes

The escapes that ‘-printf’ and ‘-fprintf’ recognise are:

\a

Alarm bell.

\b

Backspace.

\c

Stop printing from this format immediately and flush the output.

\f

Form feed.

\n

Newline.

\r

Carriage return.

\t

Horizontal tab.

\v

Vertical tab.

\\

A literal backslash (‘\’).

\0

ASCII NUL.

\NNN

The character whose ASCII code is NNN (octal).

A ‘\’ character followed by any other character is treated as an ordinary character, so they both are printed, and a warning message is printed to the standard error output (because it was probably a typo).

3.2.2 Format Directives

‘-printf’ and ‘-fprintf’ support the following format directives to print information about the file being processed. The C printf function, field width and precision specifiers are supported, as applied to string (%s) types. That is, you can specify "minimum field width"."maximum field width" for each directive. Format flags (like ‘#’ for example) may not work as you expect because many of the fields, even numeric ones, are printed with %s. The format flag ‘-’ does work; it forces left-alignment of the field.

‘%%’ is a literal percent sign. A ‘%’ 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). Don't rely on this behaviour, because other directives may be added in the future.

A ‘%’ at the end of the format argument causes undefined behaviour since there is no following character. In some locales, it may hide your door keys, while in others it may remove the final page from the novel you are reading.

• Name Directives
• Ownership Directives
• Size Directives
• Location Directives
• Time Directives
• Formatting Flags

3.2.2.1 Name Directives

%p

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

%f

File's name with any leading directories removed (only the last element).

%h

Leading directories of file's name (all but the last element and the slash before it). If the file's name contains no slashes (for example because it was named on the command line and is in the current working directory), then “%h” expands to “.”. This prevents “%h/%f” expanding to “/foo”, which would be surprising and probably not desirable.

%P

File's name with the name of the command line argument under which it was found removed from the beginning.

%H

Command line argument under which file was found.

3.2.2.2 Ownership Directives

%g

File's group name, or numeric group ID if the group has no name.

%G

File's numeric group ID.

%u

File's user name, or numeric user ID if the user has no name.

%U

File's numeric user ID.

%m

File's mode bits (in octal). If you always want to have a leading zero on the number, use the '#' format flag, for example '%#m'.

The file mode bit numbers used are the traditional Unix numbers, which will be as expected on most systems, but if your system's file mode bit layout differs from the traditional Unix semantics, you will see a difference between the mode as printed by ‘%m’ and the mode as it appears in struct stat.

%M

File's type and mode bits (in symbolic form, as for ls). This directive is supported in findutils 4.2.5 and later.

3.2.2.3 Size Directives

%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”).

%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/512, but it can also be smaller if the file is a sparse file (that is, it has “holes”).

%s

File's size in bytes.

%S

File's sparseness. This is calculated as (BLOCKSIZE*st_blocks / st_size). The exact value you will get for an ordinary file of a certain length is system-dependent. However, normally sparse files will have values less than 1.0, and files which use indirect blocks and have few holes may have a value which is greater than 1.0. The value used for BLOCKSIZE is system-dependent, but is usually 512 bytes. If the file size is zero, the value printed is undefined. On systems which lack support for st_blocks, a file's sparseness is assumed to be 1.0.

3.2.2.4 Location Directives

%d

File's depth in the directory tree (depth below a file named on the command line, not depth below the root directory). Files named on the command line have a depth of 0. Subdirectories immediately below them have a depth of 1, and so on.

%D

The device number on which the file exists (the st_dev field of struct stat), in decimal.

%F

Type of the filesystem the file is on; this value can be used for ‘-fstype’ (see Directories).

%l

Object of symbolic link (empty string if file is not a symbolic link).

%i

File's inode number (in decimal).

%n

Number of hard links to file.

%y

Type of the file as used with ‘-type’. If the file is a symbolic link, ‘l’ will be printed.

%Y

Type of the file as used with ‘-type’. If the file is a symbolic link, it is dereferenced. If the file is a broken symbolic link, ‘N’ is printed.

3.2.2.5 Time Directives

Some of these directives use the C ctime function. Its output depends on the current locale, but it typically looks like

     Wed Nov  2 00:42:36 1994

%a

File's last access time in the format returned by the C ctime function.

%Ak

File's last access time in the format specified by k (see Time Formats).

%c

File's last status change time in the format returned by the C ctime function.

%Ck

File's last status change time in the format specified by k (see Time Formats).

%t

File's last modification time in the format returned by the C ctime function.

%Tk

File's last modification time in the format specified by k (see Time Formats).

3.2.3 Time Formats

Below are the formats for the directives ‘%A’, ‘%C’, and ‘%T’, which print the file's timestamps. Some of these formats might not be available on all systems, due to differences in the C strftime function between systems.

• Time Components
• Date Components
• Combined Time Formats

3.2.3.1 Time Components

The following format directives print single components of the time.

H

hour (00..23)

I

hour (01..12)

k

hour ( 0..23)

l

hour ( 1..12)

p

locale's AM or PM

Z

time zone (e.g., EDT), or nothing if no time zone is determinable

M

minute (00..59)

S

second (00..61). There is a fractional part.

@

seconds since Jan. 1, 1970, 00:00 GMT, with fractional part.

The fractional part of the seconds field is of indeterminate length and precision. That is, the length of the fractional part of the seconds field will in general vary between findutils releases and between systems. This means that it is unwise to assume that field has any specific length. The length of this field is not usually a guide to the precision of timestamps in the underlying file system.

3.2.3.2 Date Components

The following format directives print single components of the date.

a

locale's abbreviated weekday name (Sun..Sat)

A

locale's full weekday name, variable length (Sunday..Saturday)

b

h

locale's abbreviated month name (Jan..Dec)

B

locale's full month name, variable length (January..December)

m

month (01..12)

d

day of month (01..31)

w

day of week (0..6)

j

day of year (001..366)

U

week number of year with Sunday as first day of week (00..53)

W

week number of year with Monday as first day of week (00..53)

Y

year (1970...)

y

last two digits of year (00..99)

3.2.3.3 Combined Time Formats

The following format directives print combinations of time and date components.

r

time, 12-hour (hh:mm:ss [AP]M)

T

time, 24-hour (hh:mm:ss)

X

locale's time representation (H:M:S)

c

locale's date and time in ctime format (Sat Nov 04 12:02:33 EST 1989). This format does not include any fractional part in the seconds field.

D

date (mm/dd/yy)

x

locale's date representation (mm/dd/yy)

+

Date and time, separated by '+', for example `2004-04-28+22:22:05.0000000000'. The time is given in the current timezone (which may be affected by setting the TZ environment variable). This is a GNU extension. The seconds field includes a fractional part.

3.2.3.4 Formatting Flags

The ‘%m’ and ‘%d’ directives support the ‘#’, ‘0’ and ‘+’ flags, but the other directives do not, even if they print numbers. Numeric directives that do not support these flags include

‘G’, ‘U’, ‘b’, ‘D’, ‘k’ and ‘n’.

All fields support the format flag ‘-’, which makes fields left-aligned. That is, if the field width is greater than the actual contents of the field, the requisite number of spaces are printed after the field content instead of before it.

3.3 Run Commands

You can use the list of file names created by find or locate as arguments to other commands. In this way you can perform arbitrary actions on the files.

• Single File
• Multiple Files
• Querying

3.3.1 Single File

Here is how to run a command on one file at a time.

If you use ‘-execdir’, you must ensure that the ‘$PATH’ variable contains only absolute directory names. Having an empty element in ‘$PATH’ or explicitly including ‘.’ (or any other non-absolute name) is insecure. GNU find will refuse to run if you use ‘-execdir’ and it thinks your ‘$PATH’ setting is insecure. For example:

‘/bin:/usr/bin:’

Insecure; empty path element (at the end)

‘:/bin:/usr/bin:/usr/local/bin’

Insecure; empty path element (at the start)

‘/bin:/usr/bin::/usr/local/bin’

Insecure; empty path element (two colons in a row)

‘/bin:/usr/bin:.:/usr/local/bin’

Insecure; ‘.’ is a path element (. is not an absolute file name)

‘/bin:/usr/bin:sbin:/usr/local/bin’

Insecure; ‘sbin’ is not an absolute file name

‘/bin:/usr/bin:/sbin:/usr/local/bin’

Secure (if you control the contents of those directories and any access to them)

Another similar option, ‘-exec’ is supported, but is less secure. See Security Considerations, for a discussion of the security problems surrounding ‘-exec’.

3.3.2 Multiple Files

Sometimes you need to process files one at a time. But usually this is not necessary, and, it is faster to run a command on as many files as possible at a time, rather than once per file. Doing this saves on the time it takes to start up the command each time.

The ‘-execdir’ and ‘-exec’ actions have variants that build command lines containing as many matched files as possible.