Table of Contents ***************** GNU Findutils 1 Introduction 1.1 Scope 1.2 Overview 1.3 `find' Expressions 2 Finding Files 2.1 Name 2.1.1 Base Name Patterns 2.1.2 Full Name Patterns 2.1.3 Fast Full Name Search 2.1.4 Shell Pattern Matching 2.2 Links 2.2.1 Symbolic Links 2.2.2 Hard Links 2.3 Time 2.3.1 Age Ranges 2.3.2 Comparing Timestamps 2.4 Size 2.5 Type 2.6 Owner 2.7 File Mode Bits 2.8 Contents 2.9 Directories 2.10 Filesystems 2.11 Combining Primaries With Operators 3 Actions 3.1 Print File Name 3.2 Print File Information 3.2.1 Escapes 3.2.2 Format Directives 3.2.2.1 Name Directives 3.2.2.2 Ownership Directives 3.2.2.3 Size Directives 3.2.2.4 Location Directives 3.2.2.5 Time Directives 3.2.3 Time Formats 3.2.3.1 Time Components 3.2.3.2 Date Components 3.2.3.3 Combined Time Formats 3.2.3.4 Formatting Flags 3.3 Run Commands 3.3.1 Single File 3.3.2 Multiple Files 3.3.2.1 Unsafe File Name Handling 3.3.2.2 Safe File Name Handling 3.3.2.3 Unusual Characters in File Names 3.3.2.4 Limiting Command Size 3.3.2.5 Interspersing File Names 3.3.3 Querying 3.4 Delete Files 3.5 Adding Tests 4 File Name Databases 4.1 Database Locations 4.2 Database Formats 4.2.1 LOCATE02 Database Format 4.2.2 Sample LOCATE02 Database 4.2.3 slocate Database Format 4.2.4 Old Database Format 4.3 Newline Handling 5 File Permissions 5.1 Structure of File Permissions 5.2 Symbolic Modes 5.2.1 Setting Permissions 5.2.2 Copying Existing Permissions 5.2.3 Changing Special Permissions 5.2.4 Conditional Executability 5.2.5 Making Multiple Changes 5.2.6 The Umask and Protection 5.3 Numeric Modes 6 Date input formats 6.1 General date syntax 6.2 Calendar date items 6.3 Time of day items 6.4 Time zone items 6.5 Day of week items 6.6 Relative items in date strings 6.7 Pure numbers in date strings 6.8 Seconds since the Epoch 6.9 Specifying time zone rules 6.10 Authors of `get_date' 7 Reference 7.1 Invoking `find' 7.1.1 Filesystem Traversal Options 7.1.2 Warning Messages 7.1.3 Optimisation Options 7.1.4 Debug Options 7.1.5 Find Expressions 7.2 Invoking `locate' 7.3 Invoking `updatedb' 7.4 Invoking `xargs' 7.4.1 xargs options 7.4.2 Invoking the shell from xargs 7.5 Regular Expressions 7.5.1 `findutils-default' regular expression syntax 7.5.2 `awk' regular expression syntax 7.5.3 `egrep' regular expression syntax 7.5.4 `emacs' regular expression syntax 7.5.5 `gnu-awk' regular expression syntax 7.5.6 `grep' regular expression syntax 7.5.7 `posix-awk' regular expression syntax 7.5.8 `posix-basic' regular expression syntax 7.5.9 `posix-egrep' regular expression syntax 7.5.10 `posix-extended' regular expression syntax 7.6 Environment Variables 8 Common Tasks 8.1 Viewing And Editing 8.2 Archiving 8.3 Cleaning Up 8.4 Strange File Names 8.5 Fixing Permissions 8.6 Classifying Files 9 Worked Examples 9.1 Deleting Files 9.1.1 The Traditional Way 9.1.2 Making Use of xargs 9.1.3 Unusual characters in filenames 9.1.4 Going back to -exec 9.1.5 A more secure version of -exec 9.1.6 Using the -delete action 9.1.7 Improving things still further 9.1.8 Conclusion 9.2 Copying A Subset of Files 9.3 Updating A Timestamp File 9.3.1 Updating the Timestamp The Wrong Way 9.3.2 Using the test utility to compare timestamps 9.3.3 A combined approach 9.3.4 Using -printf and sort to compare timestamps 9.3.5 Solving the problem with make 9.3.6 Coping with odd filenames too 10 Security Considerations 10.1 Levels of Risk 10.2 Security Considerations for `find' 10.2.1 Problems with -exec and filenames 10.2.2 Changing the Current Working Directory 10.2.2.1 O_NOFOLLOW 10.2.2.2 Systems without O_NOFOLLOW 10.2.3 Race Conditions with -exec 10.2.4 Race Conditions with -print and -print0 10.3 Security Considerations for `xargs' 10.4 Security Considerations for `locate' 10.4.1 Race Conditions 10.4.2 Long File Name Bugs with Old-Format Databases 10.5 Summary 11 Error Messages 11.1 Error Messages From `find' 11.2 Error Messages From xargs 11.3 Error Messages From `locate' 11.4 Error Messages From updatedb Appendix A GNU Free Documentation License `find' Primary Index 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. 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 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 . 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. 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'. *Note 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 (*note 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. *Note Actions::, for how to get more information about the matching files. 2.1 Name ======== Here are ways to search for files whose name matches a certain pattern. *Note 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. 2.1.1 Base Name Patterns ------------------------ -- Test: -name pattern -- Test: -iname pattern True if the base of the file name (the path with the leading directories removed) matches shell pattern PATTERN. For `-iname', the match is case-insensitive.(1) To ignore a whole directory tree, use `-prune' (*note Directories::). As an example, to find Texinfo source files in `/usr/local/doc': find /usr/local/doc -name '*.texi' Notice that the wildcard must be enclosed in quotes in order to protect it from expansion by the shell. As of findutils version 4.2.2, patterns for `-name' and `-iname' will match a file name with a leading `.'. For example the command `find /tmp -name \*bar' will match the file `/tmp/.foobar'. Braces within the pattern (`{}') are not considered to be special (that is, `find . -name 'foo{1,2}'' matches a file named `foo{1,2}', not the files `foo1' and `foo2'. ---------- Footnotes ---------- (1) Because we need to perform case-insensitive matching, the GNU fnmatch implementation is always used; if the C library includes the GNU implementation, we use that and otherwise we use the one from gnulib 2.1.2 Full Name Patterns ------------------------ -- Test: -path pattern -- Test: -wholename pattern True if the entire file name, starting with the command line argument under which the file was found, matches shell pattern PATTERN. To ignore a whole directory tree, use `-prune' rather than checking every file in the tree (*note 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 `cd /; find tmp -wholename /tmp' will never match anything. The name `-wholename' is GNU-specific, but `-path' is more portable; it is supported by HP-UX `find' and will soon be part of POSIX. -- Test: -ipath pattern -- Test: -iwholename pattern These tests are like `-wholename' and `-path', but the match is case-insensitive. 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 -- Test: -regex expr -- Test: -iregex expr True if the entire file name matches regular expression EXPR. This is a match on the whole path, not a search. For example, to match a file named `./fubar3', you can use the regular expression `.*bar.' or `.*b.*3', but not `f.*r3'. *Note Syntax of Regular Expressions: (emacs)Regexps, for a description of the syntax of regular expressions. For `-iregex', the match is case-insensitive. There are several varieties of regular expressions; by default this test uses POSIX basic regular expressions, but this can be changed with the option `-regextype'. -- Option: -regextype name This option controls the variety of regular expression syntax understood by the `-regex' and `-iregex' tests. This option is positional; that is, it only affects regular expressions which occur later in the command line. If this option is not given, GNU Emacs regular expressions are assumed. Currently-implemented types are `emacs' Regular expressions compatible with GNU Emacs; this is also the default behaviour if this option is not used. `posix-awk' Regular expressions compatible with the POSIX awk command (not GNU awk) `posix-basic' POSIX Basic Regular Expressions. `posix-egrep' Regular expressions compatible with the POSIX egrep command `posix-extended' POSIX Extended Regular Expressions *note Regular Expressions:: for more information on the regular expression dialects understood by GNU findutils. 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. *Note 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' (*note 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. *Note 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'. *Note 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. 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' (*note 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). -- Test: -lname pattern -- Test: -ilname pattern True if the file is a symbolic link whose contents match shell pattern PATTERN. For `-ilname', the match is case-insensitive. *Note Shell Pattern Matching::, for details about the PATTERN argument. If the `-L' option is in effect, this test will always return false for symbolic links unless they are broken. So, to list any symbolic links to `sysdep.c' in the current directory and its subdirectories, you can do: find . -lname '*sysdep.c' 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. *Note Filesystems::. -- Test: -samefile NAME File is a hard link to the same inode as NAME. If the `-L' option is in effect, symbolic links to the same file as NAME points to are also matched. -- Test: -inum n File has inode number N. The `+' and `-' qualifiers also work, though these are rarely useful. Much of the time it is easier to use `-samefile' rather than this option. 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. -- Test: -links n File has N hard links. -- Test: -links +n File has more than N hard links. -- Test: -links -n File has fewer than N hard links. 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. 2.3.1 Age Ranges ---------------- These tests are mainly useful with ranges (`+N' and `-N'). -- Test: -atime n -- Test: -ctime n -- Test: -mtime n True if the file was last accessed (or its status changed, or it was modified) N*24 hours ago. The number of 24-hour periods since the file's timestamp is always rounded down; therefore 0 means "less than 24 hours ago", 1 means "between 24 and 48 hours ago", and so forth. Fractional values are supported but this only really makes sense for the case where ranges (`+N' and `-N') are used. -- Test: -amin n -- Test: -cmin n -- Test: -mmin n True if the file was last accessed (or its status changed, or it was modified) N minutes ago. These tests provide finer granularity of measurement than `-atime' et al., but rounding is done in a similar way (again, fractions are supported). For example, to list files in `/u/bill' that were last read from 2 to 6 minutes ago: find /u/bill -amin +2 -amin -6 -- 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 find ~/ -daystart -type f -mtime 1 The `-daystart' option is unlike most other options in that it has an effect on the way that other tests are performed. The affected tests are `-amin', `-cmin', `-mmin', `-atime', `-ctime' and `-mtime'. The `-daystart' option only affects the behaviour of any tests which appear after it on the command line. 2.3.2 Comparing Timestamps -------------------------- -- Test: -newerXY reference Succeeds if timestamp `X' of the file being considered is newer than timestamp `Y' of the file `reference'. The latters `X' and `Y' can be any of the following letters: `a' Last-access time of `reference' `B' Birth time of `reference' (when this is not known, the test cannot succeed) `c' Last-change time of `reference' `m' Last-modification time of `reference' `t' The `reference' argument is interpreted as a literal time, rather than the name of a file. *Note Date input formats::, for a description of how the timestamp is understood. Tests of the form `-newerXt' are valid but tests of the form `-newertY' are not. For example the test `-newerac /tmp/foo' succeeds for all files which have been accessed more recently than `/tmp/foo' was changed. Here `X' is `a' and `Y' is `c'. Not all files have a known birth time. If `Y' is `b' and the birth time of `reference' is not available, `find' exits with an explanatory error message. If `X' is `b' and we do not know the birth time the file currently being considered, the test simply fails (that is, it behaves like `-false' does). Some operating systems (for example, most implementations of Unix) do not support file birth times. Some others, for example NetBSD-3.1, do. Even on operating systems which support file birth times, the information may not be available for specific files. For example, under NetBSD, file birth times are supported on UFS2 file systems, but not UFS1 file systems. 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$$ -- Test: -anewer file -- Test: -cnewer file -- Test: -newer file True if the file was last accessed (or its status changed, or it was modified) more recently than FILE was modified. These tests are affected by `-follow' only if `-follow' comes before them on the command line. *Note Symbolic Links::, for more information on `-follow'. As an example, to list any files modified since `/bin/sh' was last modified: find . -newer /bin/sh -- Test: -used n True if the file was last accessed N days after its status was last changed. Useful for finding files that are not being used, and could perhaps be archived or removed to save disk space. 2.4 Size ======== -- Test: -size n[bckwMG] True if the file uses N units of space, rounding up. The units are 512-byte blocks by default, but they can be changed by adding a one-character suffix to N: `b' 512-byte blocks (never 1024) `c' bytes `k' kilobytes (1024 bytes) `w' 2-byte words `M' Megabytes (units of 1048576 bytes) `G' Gigabytes (units of 1073741824 bytes) The `b' suffix always considers blocks to be 512 bytes. This is not affected by the setting (or non-setting) of the POSIXLY_CORRECT environment variable. This behaviour is different from the behaviour of the `-ls' action). If you want to use 1024-byte units, use the `k' suffix instead. The number can be prefixed with a `+' or a `-'. A plus sign indicates that the test should succeed if the file uses at least N units of storage (a common use of this test) and a minus sign indicates that the test should succeed if the file uses less than 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 consistent with the result you get for `ls -l' or `wc -c'. This handling of sparse files differs from the output of the `%k' and `%b' format specifiers for the `-printf' predicate. -- Test: -empty True if the file is empty and is either a regular file or a directory. This might help determine good candidates for deletion. This test is useful with `-depth' (*note Directories::) and `-delete' (*note Single File::). 2.5 Type ======== -- Test: -type c True if the file is of type C: `b' block (buffered) special `c' character (unbuffered) special `d' directory `p' named pipe (FIFO) `f' regular file `l' symbolic link; if `-L' is in effect, this is true only for broken symbolic links. If you want to search for symbolic links when `-L' is in effect, use `-xtype' instead of `-type'. `s' socket `D' door (Solaris) -- Test: -xtype c This test behaves the same as `-type' unless the file is a symbolic link. If the file is a symbolic link, the result is as follows (in the table below, `X' should be understood to represent any letter except `l'): ``-P -xtype l'' True if the symbolic link is broken ``-P -xtype X'' True if the (ultimate) target file is of type `X'. ``-L -xtype l'' Always true ``-L -xtype X'' False unless the symbolic link is broken In other words, for symbolic links, `-xtype' checks the type of the file that `-type' does not check. The `-H' option also affects the behaviour of `-xtype'. When `-H' is in effect, `-xtype' behaves as if `-L' had been specified when examining files listed on the command line, and as if `-P' had been specified otherwise. If neither `-H' nor `-L' was specified, `-xtype' behaves as if `-P' had been specified. *Note Symbolic Links::, for more information on `-follow' and `-L'. 2.6 Owner ========= -- Test: -user uname -- Test: -group gname True if the file is owned by user UNAME (belongs to group GNAME). A numeric ID is allowed. -- Test: -uid n -- Test: -gid n True if the file's numeric user ID (group ID) is N. These tests support ranges (`+N' and `-N'), unlike `-user' and `-group'. -- Test: -nouser -- 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 `chown' or `chgrp' program. 2.7 File Mode Bits ================== *Note 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. -- Test: -readable True if the file can be read by the invoking user. -- Test: -writable True if the file can be written by the invoking user. This is an in-principle check, and other things may prevent a successful write operation; for example, the filesystem might be full. -- Test: -executable True if the file can be executed/searched by the invoking user. -- Test: -perm pmode True if the file's mode bits match PMODE, which can be either a symbolic or numeric MODE (*note File Permissions::) optionally prefixed by `-' or `/'. A PMODE that starts with neither `-' nor `/' matches if MODE exactly matches the file mode bits. A PMODE that starts with `+' but which is not valid (for example `+a+x') is an error if the POSIXLY_CORRECT environment variable it set. Otherwise this is treated as if the initial `+' were a `/', for backward compatibility. A PMODE that starts with `-' matches if _all_ the file mode bits set in MODE are set for the file; bits not set in MODE are ignored. A PMODE that starts with `/' matches if _any_ of the file mode bits set in MODE are set for the file; bits not set in MODE are ignored. This is a GNU extension. If you don't use the `/' or `-' form with a symbolic mode string, you may have to specify a rather complex mode string. For example `-perm g=w' will only match files that have mode 0020 (that is, ones for which group write permission is the only file mode bit set). It is more likely that you will want to use the `/' or `-' forms, for example `-perm -g=w', which matches any file with group write permission. `-perm 664' Match files that have read and write permission for their owner, and group, but that the rest of the world can read but not write to. Do not match files that meet these criteria but have other file mode bits set (for example if someone can execute/search the file). `-perm -664' Match files that have read and write permission for their owner, and group, but that the rest of the world can read but not write to, without regard to the presence of any extra file mode bits (for example the executable bit). This matches a file with mode 0777, for example. `-perm /222' Match files that are writable by somebody (their owner, or their group, or anybody else). `-perm /022' Match files that are writable by either their owner or their group. The files don't have to be writable by both the owner and group to be matched; either will do. `-perm /g+w,o+w' As above. `-perm /g=w,o=w' As above. `-perm -022' Match files that are writable by both their owner and their group. `-perm -444 -perm /222 ! -perm /111' Match files that are readable for everybody, have at least one write bit set (i.e., somebody can write to them), but that cannot be executed/searched by anybody. Note that in some shells the `!' must be escaped;. `-perm -a+r -perm /a+w ! -perm /a+x' As above. `-perm -g+w,o+w' As above. Warning: If you specify `-perm /000' or `-perm /mode' where the symbolic mode `mode' has no bits set, the test matches all files. Versions of GNU `find' prior to 4.3.3 matched no files in this situation. 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. -- Option: -maxdepth levels Descend at most LEVELS (a non-negative integer) levels of directories below the command line arguments. `-maxdepth 0' means only apply the tests and actions to the command line arguments. -- Option: -mindepth levels Do not apply any tests or actions at levels less than LEVELS (a non-negative integer). `-mindepth 1' means process all files except the command line arguments. -- Option: -depth Process each directory's contents before the directory itself. Doing this is a good idea when producing lists of files to archive with `cpio' or `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. -- Option: -d This is a deprecated synonym for `-depth', for compatibility with Mac OS X, FreeBSD and OpenBSD. The `-depth' option is a POSIX feature, so it is better to use that. -- Action: -prune If the file is a directory, do not descend into it. The result is true. For example, to skip the directory `src/emacs' and all files and directories under it, and print the names of the other files found: find . -wholename './src/emacs' -prune -o -print The above command will not print `./src/emacs' among its list of results. This however is not due to the effect of the `-prune' action (which only prevents further descent, it doesn't make sure we ignore that item). Instead, this effect is due to the use of `-o'. Since the left hand side of the "or" condition has succeeded for `./src/emacs', it is not necessary to evaluate the right-hand-side (`-print') at all for this particular file. If you wanted to print that directory name you could use either an extra `-print' action: find . -wholename './src/emacs' -prune -print -o -print or use the comma operator: find . -wholename './src/emacs' -prune , -print If the `-depth' option is in effect, the subdirectories will have already been visited in any case. Hence `-prune' has no effect in this case. Because `-delete' implies `-depth', using `-prune' in combination with `-delete' may well result in the deletion of more files than you intended. -- Action: -quit Exit immediately (with return value zero if no errors have occurred). This is different to `-prune' because `-prune' only applies to the contents of pruned directories, whilt `-quit' simply makes `find' stop immediately. No child processes will be left running, but no more files specified on the command line will be processed. For example, `find /tmp/foo /tmp/bar -print -quit' will print only `/tmp/foo'. Any command lines which have been built by `-exec ... \+' or `-execdir ... \+' are invoked before the program is exited. -- 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 `.' entry. Additionally, its subdirectories (if any) each have a `..' entry linked to that directory. When `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 ("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. -- Option: -ignore_readdir_race If a file disappears after its name has been read from a directory but before `find' gets around to examining the file with `stat', don't issue an error message. If you don't specify this option, an error message will be issued. This option can be useful in system scripts (cron scripts, for example) that examine areas of the filesystem that change frequently (mail queues, temporary directories, and so forth), because this scenario is common for those sorts of directories. Completely silencing error messages from `find' is undesirable, so this option neatly solves the problem. There is no way to search one part of the filesystem with this option on and part of it with this option off, though. When this option is turned on and find discovers that one of the start-point files specified on the command line does not exist, no error message will be issued. -- Option: -noignore_readdir_race This option reverses the effect of the `-ignore_readdir_race' option. 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: -- Option: -xdev -- Option: -mount Don't descend directories on other filesystems. These options are synonyms. The other way is to check the type of filesystem each file is on, and not descend directories that are on undesirable filesystem types: -- Test: -fstype type True if the file is on a filesystem of type TYPE. The valid filesystem types vary among different versions of Unix; an incomplete list of filesystem types that are accepted on some version of Unix or another is: ext2 ext3 proc sysfs ufs 4.2 4.3 nfs tmp mfs S51K S52K You can use `-printf' with the `%F' directive to see the types of your filesystems. The `%D' directive shows the device number. *Note Print File Information::. `-fstype' is usually used with `-prune' to avoid searching remote filesystems (*note Directories::). 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: -- Test: -true Always true. -- Test: -false Always false. 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. 3.1 Print File Name =================== -- Action: -print True; print the entire file name on the standard output, followed by a newline. If there is the faintest possibility that one of the files for which you are searching might contain a newline, you should use `-print0' instead. -- Action: -fprint file True; print the entire file name into file FILE, followed by a newline. If FILE does not exist when `find' is run, it is created; if it does exist, it is truncated to 0 bytes. The named output file is always created, even if no output is sent to it. The file names `/dev/stdout' and `/dev/stderr' are handled specially; they refer to the standard output and standard error output, respectively. If there is the faintest possibility that one of the files for which you are searching might contain a newline, you should use `-fprint0' instead. 3.2 Print File Information ========================== -- Action: -ls True; list the current file in `ls -dils' format on the standard output. The output looks like this: 204744 17 -rw-r--r-- 1 djm staff 17337 Nov 2 1992 ./lwall-quotes The fields are: 1. The inode number of the file. *Note Hard Links::, for how to find files based on their inode number. 2. the number of blocks in the file. The block counts are of 1K blocks, unless the environment variable `POSIXLY_CORRECT' is set, in which case 512-byte blocks are used. *Note Size::, for how to find files based on their size. 3. The file's type and file mode bits. The type is shown as a dash for a regular file; for other file types, a letter like for `-type' is used (*note Type::). The file mode bits are read, write, and execute/search for the file's owner, its group, and other users, respectively; a dash means the permission is not granted. *Note File Permissions::, for more details about file permissions. *Note Mode Bits::, for how to find files based on their file mode bits. 4. The number of hard links to the file. 5. The user who owns the file. 6. The file's group. 7. The file's size in bytes. 8. The date the file was last modified. 9. The file's name. `-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 `-ls', `-fls', `-print', `-fprint', `-printf' and `-fprintf'. -- Action: -fls file True; like `-ls' but write to FILE like `-fprint' (*note Print File Name::). The named output file is always created, even if no output is sent to it. -- Action: -printf format True; print FORMAT on the standard output, interpreting `\' escapes and `%' directives. Field widths and precisions can be specified as with the `printf' C function. Format flags (like `#' for example) may not work as you expect because many of the fields, even numeric ones, are printed with %s. Numeric flags which are affected in this way include G, U, b, D, k and n. This difference in behaviour means though that the format flag `-' will work; it forces left-alignment of the field. Unlike `-print', `-printf' does not add a newline at the end of the string. If you want a newline at the end of the string, add a `\n'. -- Action: -fprintf file format True; like `-printf' but write to FILE like `-fprint' (*note Print File Name::). The output file is always created, even if no output is ever sent to it. 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. 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' (*note 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 (*note 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 (*note 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 (*note 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. 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. 3.3.1 Single File ----------------- Here is how to run a command on one file at a time. -- Action: -execdir command ; Execute COMMAND; true if zero status is returned. `find' takes all arguments after `-exec' to be part of the command until an argument consisting of `;' is reached. It replaces the string `{}' by the current file name being processed everywhere it occurs in the command. Both of these constructions need to be escaped (with a `\') or quoted to protect them from expansion by the shell. The command is executed in the directory in which `find' was run. For example, to compare each C header file in or below the current directory with the file `/tmp/master': find . -name '*.h' -execdir diff -u '{}' /tmp/master ';' 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. *Note Security Considerations::, for a discussion of the security problems surrounding `-exec'. -- Action: -exec command ; This insecure variant of the `-execdir' action is specified by POSIX. The main difference is that the command is executed in the directory from which `find' was invoked, meaning that `{}' is expanded to a relative path starting with the name of one of the starting directories, rather than just the basename of the matched file. While some implementations of `find' replace the `{}' only where it appears on its own in an argument, GNU `find' replaces `{}' wherever it appears. 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. -- Action: -execdir command {} + This works as for `-execdir command ;', except that the `{}' at the end of the command is expanded to a list of names of matching files. This expansion is done in such a way as to avoid exceeding the maximum command line length available on the system. Only one `{}' is allowed within the command, and it must appear at the end, immediately before the `+'. A `+' appearing in any position other than immediately after `{}' is not considered to be special (that is, it does not terminate the command). -- Action: -exec command {} + This insecure variant of the `-execdir' action is specified by POSIX. The main difference is that the command is executed in the directory from which `find' was invoked, meaning that `{}' is expanded to a relative path starting with the name of one of the starting directories, rather than just the basename of the matched file. Before `find' exits, any partially-built command lines are executed. This happens even if the exit was caused by the `-quit' action. However, some types of error (for example not being able to invoke `stat()' on the current directory) can cause an immediate fatal exit. In this situation, any partially-built command lines will not be invoked (this prevents possible infinite loops). At first sight, it looks like the list of filenames to be processed can only be at the end of the command line, and that this might be a problem for some comamnds (`cp' and `rsync' for example). However, there is a slightly obscure but powerful workarouund for this problem which takes advantage of the behaviour of `sh -c':- find startpoint -tests ... -exec sh -c 'scp "$@" remote:/dest' sh {} + In the example above, the filenames we want to work on need to occur on the `scp' command line before the name of the destination. We use the shell to invoke the command `scp "$@" remote:/dest' and the shell expands `"$@"' to the list of filenames we want to process. Another, but less secure, way to run a command on more than one file at once, is to use the `xargs' command, which is invoked like this: xargs [OPTION...] [COMMAND [INITIAL-ARGUMENTS]] `xargs' normally reads arguments from the standard input. These arguments are delimited by blanks (which can be protected with double or single quotes or a backslash) or newlines. It executes the COMMAND (default is `/bin/echo') one or more times with any INITIAL-ARGUMENTS followed by arguments read from standard input. Blank lines on the standard input are ignored. If the `-L' option is in use, trailing blanks indicate that `xargs' should consider the following line to be part of this one. Instead of blank-delimited names, it is safer to use `find -print0' or `find -fprint0' and process the output by giving the `-0' or `--null' option to GNU `xargs', GNU `tar', GNU `cpio', or `perl'. The `locate' command also has a `-0' or `--null' option which does the same thing. You can use shell command substitution (backquotes) to process a list of arguments, like this: grep -l sprintf `find $HOME -name '*.c' -print` However, that method produces an error if the length of the `.c' file names exceeds the operating system's command line length limit. `xargs' avoids that problem by running the command as many times as necessary without exceeding the limit: find $HOME -name '*.c' -print | xargs grep -l sprintf However, if the command needs to have its standard input be a terminal (`less', for example), you have to use the shell command substitution method or use the `--arg-file' option of `xargs'. The `xargs' command will process all its input, building command 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 `--eof' option. 3.3.2.1 Unsafe File Name Handling ................................. Because file names can contain quotes, backslashes, blank characters, and even newlines, it is not safe to process them using `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. Error messages issued by `find' and `locate' quote unusual characters in file names in order to prevent unwanted changes in the terminal's state. In many applications, if `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 `cron', then any user can remove any file on the system: find / -name '#*' -atime +7 -print | xargs rm For example, you could do something like this: eg$ echo > '# vmunix' and then `cron' would delete `/vmunix', if it ran `xargs' with `/' as its current directory. To delete other files, for example `/u/joeuser/.plan', you could do this: eg$ mkdir '# ' eg$ cd '# ' eg$ mkdir u u/joeuser u/joeuser/.plan' ' eg$ echo > u/joeuser/.plan' /#foo' eg$ cd .. eg$ find . -name '#*' -print | xargs echo ./# ./# /u/joeuser/.plan /#foo 3.3.2.2 Safe File Name Handling ............................... Here is how to make `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 `-0' or `--null' option to GNU `xargs', GNU `tar', GNU `cpio', or `perl'. -- Action: -print0 True; print the entire file name on the standard output, followed by a null character. -- Action: -fprint0 file True; like `-print0' but write to FILE like `-fprint' (*note Print File Name::). The output file is always created. As of findutils version 4.2.4, the `locate' program also has a `--null' option which does the same thing. For similarity with `xargs', the short form of the option `-0' can also be used. If you want to be able to handle file names safely but need to run commands which want to be connected to a terminal on their input, you can use the `--arg-file' option to `xargs' like this: find / -name xyzzy -print0 > list xargs --null --arg-file=list munge The example above runs the `munge' program on all the files named `xyzzy' that we can find, but `munge''s input will still be the terminal (or whatever the shell was using as standard input). If your shell has the "process substitution" feature `<(...)', you can do this in just one step: xargs --null --arg-file=<(find / -name xyzzy -print0) munge 3.3.2.3 Unusual Characters in File Names ........................................ As discussed above, you often need to be careful about how the names of files are handled by `find' and other programs. If the output of `find' is not going to another program but instead is being shown on a terminal, this can still be a problem. For example, some character sequences can reprogram the function keys on some terminals. *Note Security Considerations::, for a discussion of other security problems relating to `find'. Unusual characters are handled differently by various actions, as described below. `-print0' `-fprint0' Always print the exact file name, unchanged, even if the output is going to a terminal. `-ok' `-okdir' Always print the exact file name, unchanged. This will probably change in a future release. `-ls' `-fls' Unusual characters are always escaped. White space, backslash, and double quote characters are printed using C-style escaping (for example `\f', `\"'). Other unusual characters are printed using an octal escape. Other printable characters (for `-ls' and `-fls' these are the characters between octal 041 and 0176) are printed as-is. `-printf' `-fprintf' If the output is not going to a terminal, it is printed as-is. Otherwise, the result depends on which directive is in use: %D, %F, %H, %Y, %y These expand to values which are not under control of files' owners, and so are printed as-is. %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' owners but which cannot be used to send arbitrary data to the terminal, and so these are printed as-is. %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 `ls'. This is not the same quoting mechanism as the one used for `-ls' and `fls'. If you are able to decide what format to use for the output of `find' then it is normally better to use `\0' as a terminator than to use newline, as file names can contain white space and newline characters. `-print' `-fprint' Quoting is handled in the same way as for the `%p' directive of `-printf' and `-fprintf'. If you are using `find' in a script or in a situation where the matched files might have arbitrary names, you should consider using `-print0' instead of `-print'. The `locate' program quotes and escapes unusual characters in file names in the same way as `find''s `-print' action. The behaviours described above may change soon, as the treatment of unprintable characters is harmonised for `-ls', `-fls', `-print', `-fprint', `-printf' and `-fprintf'. 3.3.2.4 Limiting Command Size ............................. `xargs' gives you control over how many arguments it passes to the command each time it executes it. By default, it uses up to `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. `--no-run-if-empty' `-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. This option is a GNU extension. `--max-lines[=MAX-LINES]' `-L MAX-LINES' `-l[MAX-LINES]' Use at most MAX-LINES nonblank input lines per command line; MAX-LINES defaults to 1 if omitted; omitting the argument is not allowed in the case of the `-L' option. Trailing blanks cause an input line to be logically continued on the next input line, for the purpose of counting the lines. Implies `-x'. The preferred name for this option is `-L' as this is specified by POSIX. `--max-args=MAX-ARGS' `-n MAX-ARGS' Use at most MAX-ARGS arguments per command line. Fewer than MAX-ARGS arguments will be used if the size (see the `-s' option) is exceeded, unless the `-x' option is given, in which case `xargs' will exit. `--max-chars=MAX-CHARS' `-s MAX-CHARS' Use at most MAX-CHARS characters per command line, including the 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. You can use `--show-limits' option to understand the command-line limits applying to `xargs' and how this is affected by any other options. The POSIX limits shown when you do this have already been adjusted to take into account the size of your environment variables. The largest allowed value is system-dependent, and is calculated as the argument length limit for exec, less the size of your environment, less 2048 bytes of headroom. If this value is more than 128KiB, 128Kib is used as the default value; otherwise, the default value is the maximum. `--max-procs=MAX-PROCS' `-P MAX-PROCS' Run up to MAX-PROCS processes at a time; the default is 1. If MAX-PROCS is 0, `xargs' will run as many processes as possible at a time. Use the `-n', `-s', or `-L' option with `-P'; otherwise chances are that the command will be run only once. 3.3.2.5 Interspersing File Names ................................ `xargs' can insert the name of the file it is processing between arguments you give for the command. Unless you also give options to limit the command size (*note Limiting Command Size::), this mode of operation is equivalent to `find -exec' (*note Single File::). `--replace[=REPLACE-STR]' `-I REPLACE-STR' `-i REPLACE-STR' Replace occurrences of REPLACE-STR in the initial arguments with names read from the input. Also, unquoted blanks do not terminate arguments; instead, the input is split at newlines only. For the `-i' option, if REPLACE-STR is omitted for `--replace' or `-i', it defaults to `{}' (like for `find -exec'). Implies `-x' and `-l 1'. `-i' is deprecated in favour of `-I'. As an example, to sort each file in the `bills' directory, leaving the output in that file name with `.sorted' appended, you could do: find bills -type f | xargs -I XX sort -o XX.sorted XX The equivalent command using `find -execdir' is: find bills -type f -execdir sort -o '{}.sorted' '{}' ';' When you use the `-I' option, each line read from the input is buffered internally. This means that there is an upper limit on the length of input line that xargs will accept when used with the `-I' option. To work around this limitation, you can use the `-s' option to increase the amount of buffer space that xargs uses, and you can also use an extra invocation of xargs to ensure that very long lines do not occur. For example: somecommand | xargs -s 50000 echo | xargs -I '{}' -s 100000 rm '{}' Here, the first invocation of `xargs' has no input line length limit because it doesn't use the `-I' option. The second invocation of `xargs' does have such a limit, but we have ensured that it never encounters a line which is longer than it can handle. This is not an ideal solution. Instead, the `-I' option should not impose a line length limit (apart from any limit imposed by the operating system) and so one might consider this limitation to be a bug. A better solution would be to allow `xargs -I' to automatically move to a larger value for the `-s' option when this is needed. This sort of problem doesn't occur with the output of `find' because it emits just one filename per line. 3.3.3 Querying -------------- To ask the user whether to execute a command on a single file, you can use the `find' primary `-okdir' instead of `-execdir', and the `find' primary `-ok' instead of `-exec': -- Action: -okdir command ; Like `-execdir' (*note Single File::), but ask the user first (on the standard input); if the response does not start with `y' or `Y', do not run the command, and return false. If the command is run, its standard input is redirected from `/dev/null'. -- Action: -ok command ; This insecure variant of the `-okdir' action is specified by POSIX. The main difference is that the command is executed in the directory from which `find' was invoked, meaning that `{}' is expanded to a relative path starting with the name of one of the starting directories, rather than just the basename of the matched file. If the command is run, its standard input is redirected from `/dev/null'. When processing multiple files with a single command, to query the user you give `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 (*note Limiting Command Size::). `--interactive' `-p' Prompt the user about whether to run each command line and read a line from the terminal. Only run the command line if the response starts with `y' or `Y'. Implies `-t'. 3.4 Delete Files ================ -- Action: -delete Delete files or directories; true if removal succeeded. If the removal failed, an error message is issued. The use of the `-delete' action on the command line automatically turns on the `-depth' option (*note find Expressions::). This can be surprising if you were previously just testing with `-print', so it is usually best to remember to use `-depth' explicitly. If `-delete' fails, `find''s exit status will be nonzero (when it eventually exits). 3.5 Adding Tests ================ You can test for file attributes that none of the `find' builtin tests check. To do this, use `xargs' to run a program that filters a list of files printed by `find'. If possible, use `find' builtin tests to pare down the list, so the program run by `xargs' has less work to do. The tests builtin to `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 a good idea to implement "extended" tests by using `xargs'. For example, here is a way to print the names of all of the unstripped binaries in the `/usr/local' directory tree. Builtin tests avoid running `file' on files that are not regular files or are not executable. find /usr/local -type f -perm /a=x | xargs file | grep 'not stripped' | cut -d: -f1 The `cut' program removes everything after the file name from the output of `file'. However, using `xargs' can present important security problems (*note Security Considerations::). These can be avoided by using `-execdir'. The `-execdir' action is also a useful way of putting your own test in the middle of a set of other tests or actions for `find' (for example, you might want to use `-prune'). To place a special test somewhere in the middle of a `find' expression, you can use `-execdir' (or, less securely, `-exec') to run a program that performs the test. Because `-execdir' evaluates to the exit status of the executed program, you can use a program (which can be a shell script) that tests for a 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 _after_ the builtin tests, because it starts a new process which could be avoided if a builtin test evaluates to false. Here is a shell script called `unstripped' that checks whether its argument is an unstripped binary file: #! /bin/sh file "$1" | grep -q "not stripped" This script relies on the shell exiting with the status of the last command in the pipeline, in this case `grep'. The `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 in your search path). It lists the stripped executables (and shell scripts) in the file `sbins' and the unstripped ones in `ubins'. find /usr/local -type f -perm /a=x \ \( -execdir unstripped '{}' \; -fprint ubins -o -fprint sbins \) 4 File Name Databases ********************* The file name databases used by `locate' contain lists of files that were in particular directory trees when the databases were last updated. The file name of the default database is determined when `locate' and `updatedb' are configured and installed. The frequency with which the databases are updated and the directories for which they contain entries depend on how often `updatedb' is run, and with which arguments. You can obtain some statistics about the databases by using `locate --statistics'. 4.1 Database Locations ====================== There can be multiple file name databases. Users can select which databases `locate' searches using the `LOCATE_PATH' environment variable or a command line option. 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. File name databases are updated by running the `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. `updatedb' is then run for each filesystem on the fileserver where that filesystem is on a local disk, to prevent thrashing the network. *Note Invoking updatedb::, for the description of the options to `updatedb'. These options can be used to specify which directories are indexed by each database file. The default location for the locate database depends on how findutils is built, but the findutils installation accompanying this manual uses the default location `/usr/local/var/locatedb'. If no database exists at `/usr/local/var/locatedb' but the user did not specify where to look (by using `-d' or setting `LOCATE_PATH'), then `locate' will also check for a "secure" database in `/var/lib/slocate/slocate.db'. 4.2 Database Formats ==================== 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 `locate' version 4.0 to allow machines with different byte orderings to share the databases. GNU `locate' can read both the old and new database formats. However, old versions of `locate' (on other Unix systems, or GNU `locate' before version 4.0) produce incorrect results if run against a database in something other than the old format. Support for the old database format will eventually be discontinued, first in `updatedb' and later in `locate'. If you run `locate --statistics', the resulting summary indicates the type of each `locate' database. You select which database format `updatedb' will use with the `--dbformat' option. 4.2.1 LOCATE02 Database Format ------------------------------ `updatedb' runs a program called `frcode' to "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). Every database begins with a dummy entry for a file called `LOCATE02', which `locate' checks for to ensure that the database file has the correct format; it ignores the entry in doing the search. 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. In the output of `locate --statistics', the new database format is referred to as `LOCATE02'. 4.2.2 Sample LOCATE02 Database ------------------------------ Sample input to `frcode': /usr/src /usr/src/cmd/aardvark.c /usr/src/cmd/armadillo.c /usr/tmp/zoo Length of the longest prefix of the preceding entry to share: 0 /usr/src 8 /cmd/aardvark.c 14 rmadillo.c 5 tmp/zoo Output from `frcode', with trailing nulls changed to newlines and count bytes made printable: 0 LOCATE02 0 /usr/src 8 /cmd/aardvark.c 6 rmadillo.c -9 tmp/zoo (6 = 14 - 8, and -9 = 5 - 14) 4.2.3 slocate Database Format ----------------------------- The `slocate' program uses a database format similar to, but not quite the same as, GNU `locate'. The first byte of the database specifies its "security level". If the security level is 0, `slocate' will read, match and print filenames on the basis of the information in the database only. However, if the security level byte is 1, `slocate' omits entries from its output if the invoking user is unable to access them. The second byte of the database is zero. The second byte is immediately followed by the first database entry. The first entry in the database is not preceded by any differential count or dummy entry. Instead the differential count for the first item is assumed to be zero. .P Starting with the second entry (if any) in the database, data is interpreted as for the GNU LOCATE02 format. 4.2.4 Old Database Format ------------------------- The old database format is used by Unix `locate' and `find' programs and earlier releases of the GNU ones. `updatedb' produces this format if given the `--old-format' option. `updatedb' runs programs called `bigram' and `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. 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 cannot faithfully store entries with non-ASCII characters. It therefore should not be used in internationalised environments. That is, most installations should not use it. Because the long counts are stored by the `code' program as native-order machine words, the database format is not eaily used in environments which differ in terms of byte order. If locate databases are to be shared between machines, the LOCATE02 database format should be used. This has other benefits as discussed above. However, the length of the filename currently being processed can normally be used to place reasonable limits on the long counts and so this information is used by locate to help it guess the byte ordering of the old format database. Unless it finds evidence to the contrary, `locate' will assume that the byte order of the database is the same as the native byte order of the machine running `locate'. The output of `locate --statistics' also includes information about the byte order of old-format databases. The output of `locate --statistics' will give an incorrect count of the number of file names containing newlines or high-bit characters for old-format databases. Old versions of GNU `locate' fail to correctly handle very long file names, possibly leading to security problems relating to a heap buffer overrun. *Note Security Considerations for locate::, for a detailed explanation. 4.3 Newline Handling ==================== 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 list of files before they are presented to `frcode'. If the system's sort command allows its input list of files to be separated with null characters via the `-z' option, this option is used and therefore `updatedb' and `locate' will both correctly handle file names containing newlines. If the `sort' command lacks support for this, the list of files is delimited with 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, file names with embedded newlines are not correctly handled. There is no technical limitation which enforces this, it's just that the `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 `sort', newlines will be correctly handled at all times. Otherwise, newlines may not be correctly handled. 5 File Permissions ****************** Each file has a set of "permissions" that control the kinds of access that users have to that file. The permissions for a file are also called its "access mode". They can be represented either in symbolic form or as an octal number. 5.1 Structure of File Permissions ================================= There are three kinds of permissions that a user can have for a file: 1. permission to read the file. For directories, this means permission to list the contents of the directory. 2. permission to write to (change) the file. For directories, this means permission to create and remove files in the directory. 3. permission to execute the file (run it as a program). For directories, this means permission to access files in the directory. There are three categories of users who may have different permissions to perform any of the above operations on a file: 1. the file's owner; 2. other users who are in the file's group; 3. everyone else. Files are given an owner and group when they are created. Usually the owner is the current user and the group is the group of the directory the file is in, but this varies with the operating system, the file system the file is created on, and the way the file is created. You can change the owner and group of a file by using the `chown' and `chgrp' commands. In addition to the three sets of three permissions listed above, a file's permissions have three special components, which affect only executable files (programs) and, on some systems, directories: 1. Set the process's effective user ID to that of the file upon execution (called the "setuid bit"). No effect on directories. 2. Set the process's effective group ID to that of the file upon execution (called the "setgid bit"). For directories on some systems, put files created in the directory into the same group as the directory, no matter what group the user who creates them is in. 3. prevent users from removing or renaming a file in a directory unless they own the file or the directory; this is called the "restricted deletion flag" for the directory. For regular files on some systems, save the program's text image on the swap device so it will load more quickly when run; this is called the "sticky bit". In addition to the permissions listed above, there may be file attributes specific to the file system, e.g: access control lists (ACLs), whether a file is compressed, whether a file can be modified (immutability), whether a file can be dumped. These are usually set using programs specific to the file system. For example: ext2 On GNU and GNU/Linux the file permissions ("attributes") specific to the ext2 file system are set using `chattr'. FFS On FreeBSD the file permissions ("flags") specific to the FFS file system are set using `chrflags'. Although a file's permission "bits" allow an operation on that file, that operation may still fail, because: * the file-system-specific permissions do not permit it; * the file system is mounted as read-only. For example, if the immutable attribute is set on a file, it cannot be modified, regardless of the fact that you may have just run `chmod a+w FILE'. 5.2 Symbolic Modes ================== "Symbolic modes" represent changes to files' permissions as operations on single-character symbols. They allow you to modify either all or selected parts of files' permissions, optionally based on their previous values, and perhaps on the current `umask' as well (*note Umask and Protection::). The format of symbolic modes is: [ugoa...][+-=]PERMS...[,...] where PERMS is either zero or more letters from the set `rwxXst', or a single letter from the set `ugo'. The following sections describe the operators and other details of symbolic modes. 5.2.1 Setting Permissions ------------------------- The basic symbolic operations on a file's permissions are adding, removing, and setting the permission that certain users have to read, write, and execute the file. These operations have the following format: USERS OPERATION PERMISSIONS The spaces between the three parts above are shown for readability only; symbolic modes cannot contain spaces. The USERS part tells which users' access to the file is changed. It consists of one or more of the following letters (or it can be empty; *note Umask and Protection::, for a description of what happens then). When more than one of these letters is given, the order that they are in does not matter. `u' the user who owns the file; `g' other users who are in the file's group; `o' all other users; `a' all users; the same as `ugo'. The OPERATION part tells how to change the affected users' access to the file, and is one of the following symbols: `+' to add the PERMISSIONS to whatever permissions the USERS already have for the file; `-' to remove the PERMISSIONS from whatever permissions the USERS already have for the file; `=' to make the PERMISSIONS the only permissions that the USERS have for the file. The PERMISSIONS part tells what kind of access to the file should be changed; it is normally zero or more of the following letters. As with the USERS part, the order does not matter when more than one letter is given. Omitting the PERMISSIONS part is useful only with the `=' operation, where it gives the specified USERS no access at all to the file. `r' the permission the USERS have to read the file; `w' the permission the USERS have to write to the file; `x' the permission the USERS have to execute the file. For example, to give everyone permission to read and write a file, but not to execute it, use: a=rw To remove write permission for all users other than the file's owner, use: go-w The above command does not affect the access that the owner of the file has to it, nor does it affect whether other users can read or execute the file. To give everyone except a file's owner no permission to do anything with that file, use the mode below. Other users could still remove the file, if they have write permission on the directory it is in. go= Another way to specify the same thing is: og-rwx 5.2.2 Copying Existing Permissions ---------------------------------- You can base a file's permissions on its existing permissions. To do this, instead of using a series of `r', `w', or `x' letters after the operator, you use the letter `u', `g', or `o'. For example, the mode o+g adds the permissions for users who are in a file's group to the permissions that other users have for the file. Thus, if the file started out as mode 664 (`rw-rw-r--'), the above mode would change it to mode 666 (`rw-rw-rw-'). If the file had started out as mode 741 (`rwxr----x'), the above mode would change it to mode 745 (`rwxr--r-x'). The `-' and `=' operations work analogously. 5.2.3 Changing Special Permissions ---------------------------------- In addition to changing a file's read, write, and execute permissions, you can change its special permissions. *Note Mode Structure::, for a summary of these permissions. To change a file's permission to set the user ID on execution, use `u' in the USERS part of the symbolic mode and `s' in the PERMISSIONS part. To change a file's permission to set the group ID on execution, use `g' in the USERS part of the symbolic mode and `s' in the PERMISSIONS part. To change a file's permission to set the restricted deletion flag or sticky bit, omit the USERS part of the symbolic mode (or use `a') and put `t' in the PERMISSIONS part. For example, to add set-user-ID permission to a program, you can use the mode: u+s To remove both set-user-ID and set-group-ID permission from it, you can use the mode: ug-s To set the restricted deletion flag or sticky bit, you can use the mode: +t The combination `o+s' has no effect. On GNU systems the combinations `u+t' and `g+t' have no effect, and `o+t' acts like plain `+t'. The `=' operator is not very useful with special permissions; for example, the mode: o=t does set the restricted deletion flag or sticky bit, but it also removes all read, write, and execute permissions that users not in the file's group might have had for it. 5.2.4 Conditional Executability ------------------------------- There is one more special type of symbolic permission: if you use `X' instead of `x', execute permission is affected only if the file is a directory or already had execute permission. For example, this mode: a+X gives all users permission to search directories, or to execute files if anyone could execute them before. 5.2.5 Making Multiple Changes ----------------------------- The format of symbolic modes is actually more complex than described above (*note Setting Permissions::). It provides two ways to make multiple changes to files' permissions. The first way is to specify multiple OPERATION and PERMISSIONS parts after a USERS part in the symbolic mode. For example, the mode: og+rX-w gives users other than the owner of the file read permission and, if it is a directory or if someone already had execute permission to it, gives them execute permission; and it also denies them write permission to the file. It does not affect the permission that the owner of the file has for it. The above mode is equivalent to the two modes: og+rX og-w The second way to make multiple changes is to specify more than one simple symbolic mode, separated by commas. For example, the mode: a+r,go-w gives everyone permission to read the file and removes write permission on it for all users except its owner. Another example: u=rwx,g=rx,o= sets all of the non-special permissions for the file explicitly. (It gives users who are not in the file's group no permission at all for it.) The two methods can be combined. The mode: a+r,g+x-w gives all users permission to read the file, and gives users who are in the file's group permission to execute it, as well, but not permission to write to it. The above mode could be written in several different ways; another is: u+r,g+rx,o+r,g-w 5.2.6 The Umask and Protection ------------------------------ If the USERS part of a symbolic mode is omitted, it defaults to `a' (affect all users), except that any permissions that are _set_ in the system variable `umask' are _not affected_. The value of `umask' can be set using the `umask' command. Its default value varies from system to system. Omitting the USERS part of a symbolic mode is generally not useful with operations other than `+'. It is useful with `+' because it allows you to use `umask' as an easily customizable protection against giving away more permission to files than you intended to. As an example, if `umask' has the value 2, which removes write permission for users who are not in the file's group, then the mode: +w adds permission to write to the file to its owner and to other users who are in the file's group, but _not_ to other users. In contrast, the mode: a+w ignores `umask', and _does_ give write permission for the file to all users. 5.3 Numeric Modes ================= As an alternative to giving a symbolic mode, you can give an octal (base 8) number that represents the new mode. This number is always interpreted in octal; you do not have to add a leading 0, as you do in C. Mode 0055 is the same as mode 55. A numeric mode is usually shorter than the corresponding symbolic mode, but it is limited in that it cannot take into account a file's previous permissions; it can only set them absolutely. The permissions granted to the user, to other users in the file's group, and to other users not in the file's group each require three bits, which are represented as one octal digit. The three special permissions also require one bit each, and they are as a group represented as another octal digit. Here is how the bits are arranged, starting with the lowest valued bit: Value in Corresponding Mode Permission Other users not in the file's group: 1 Execute 2 Write 4 Read Other users in the file's group: 10 Execute 20 Write 40 Read The file's owner: 100 Execute 200 Write 400 Read Special permissions: 1000 Restricted deletion flag or sticky bit 2000 Set group ID on execution 4000 Set user ID on execution For example, numeric mode 4755 corresponds to symbolic mode `u=rwxs,go=rx', and numeric mode 664 corresponds to symbolic mode `ug=rw,o=r'. Numeric mode 0 corresponds to symbolic mode `a='. 6 Date input formats ******************** First, a quote: Our units of temporal measurement, from seconds on up to months, are so complicated, asymmetrical and disjunctive so as to make coherent mental reckoning in time all but impossible. Indeed, had some tyrannical god contrived to enslave our minds to time, to make it all but impossible for us to escape subjection to sodden routines and unpleasant surprises, he could hardly have done better than handing down our present system. It is like a set of trapezoidal building blocks, with no vertical or horizontal surfaces, like a language in which the simplest thought demands ornate constructions, useless particles and lengthy circumlocutions. Unlike the more successful patterns of language and science, which enable us to face experience boldly or at least level-headedly, our system of temporal calculation silently and persistently encourages our terror of time. ... It is as though architects had to measure length in feet, width in meters and height in ells; as though basic instruction manuals demanded a knowledge of five different languages. It is no wonder then that we often look into our own immediate past or future, last Tuesday or a week from Sunday, with feelings of helpless confusion. ... -- Robert Grudin, `Time and the Art of Living'. This section describes the textual date representations that GNU programs accept. These are the strings you, as a user, can supply as arguments to the various programs. The C interface (via the `get_date' function) is not described here. 6.1 General date syntax ======================= A "date" is a string, possibly empty, containing many items separated by whitespace. The whitespace may be omitted when no ambiguity arises. The empty string means the beginning of today (i.e., midnight). Order of the items is immaterial. A date string may contain many flavors of items: * calendar date items * time of day items * time zone items * day of the week items * relative items * pure numbers. We describe each of these item types in turn, below. A few ordinal numbers may be written out in words in some contexts. This is most useful for specifying day of the week items or relative items (see below). Among the most commonly used ordinal numbers, the word `last' stands for -1, `this' stands for 0, and `first' and `next' both stand for 1. Because the word `second' stands for the unit of time there is no way to write the ordinal number 2, but for convenience `third' stands for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6, `seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10, `eleventh' for 11 and `twelfth' for 12. When a month is written this way, it is still considered to be written numerically, instead of being "spelled in full"; this changes the allowed strings. In the current implementation, only English is supported for words and abbreviations like `AM', `DST', `EST', `first', `January', `Sunday', `tomorrow', and `year'. The output of the `date' command is not always acceptable as a date string, not only because of the language problem, but also because there is no standard meaning for time zone items like `IST'. When using `date' to generate a date string intended to be parsed later, specify a date format that is independent of language and that does not use time zone items other than `UTC' and `Z'. Here are some ways to do this: $ LC_ALL=C TZ=UTC0 date Mon Mar 1 00:21:42 UTC 2004 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' 2004-03-01 00:21:42Z $ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. 2004-02-29 16:21:42,692722128-0800 $ date --rfc-2822 # a GNU extension Sun, 29 Feb 2004 16:21:42 -0800 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. 2004-02-29 16:21:42 -0800 $ date +'@%s.%N' # %s and %N are GNU extensions. @1078100502.692722128 Alphabetic case is completely ignored in dates. Comments may be introduced between round parentheses, as long as included parentheses are properly nested. Hyphens not followed by a digit are currently ignored. Leading zeros on numbers are ignored. Invalid dates like `2005-02-29' or times like `24:00' are rejected. In the typical case of a host that does not support leap seconds, a time like `23:59:60' is rejected even if it corresponds to a valid leap second. 6.2 Calendar date items ======================= A "calendar date item" specifies a day of the year. It is specified differently, depending on whether the month is specified numerically or literally. All these strings specify the same calendar date: 1972-09-24 # ISO 8601. 72-9-24 # Assume 19xx for 69 through 99, # 20xx for 00 through 68. 72-09-24 # Leading zeros are ignored. 9/24/72 # Common U.S. writing. 24 September 1972 24 Sept 72 # September has a special abbreviation. 24 Sep 72 # Three-letter abbreviations always allowed. Sep 24, 1972 24-sep-72 24sep72 The year can also be omitted. In this case, the last specified year is used, or the current year if none. For example: 9/24 sep 24 Here are the rules. For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed, where YEAR is any positive number, MONTH is a number between 01 and 12, and DAY is a number between 01 and 31. A leading zero must be present if a number is less than ten. If YEAR is 68 or smaller, then 2000 is added to it; otherwise, if YEAR is less than 100, then 1900 is added to it. The construct `MONTH/DAY/YEAR', popular in the United States, is accepted. Also `MONTH/DAY', omitting the year. Literal months may be spelled out in full: `January', `February', `March', `April', `May', `June', `July', `August', `September', `October', `November' or `December'. Literal months may be abbreviated to their first three letters, possibly followed by an abbreviating dot. It is also permitted to write `Sept' instead of `September'. When months are written literally, the calendar date may be given as any of the following: DAY MONTH YEAR DAY MONTH MONTH DAY YEAR DAY-MONTH-YEAR Or, omitting the year: MONTH DAY 6.3 Time of day items ===================== A "time of day item" in date strings specifies the time on a given day. Here are some examples, all of which represent the same time: 20:02:00.000000 20:02 8:02pm 20:02-0500 # In EST (U.S. Eastern Standard Time). More generally, the time of day may be given as `HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE is a number between 0 and 59, and SECOND is a number between 0 and 59 possibly followed by `.' or `,' and a fraction containing one or more digits. Alternatively, `:SECOND' can be omitted, in which case it is taken to be zero. On the rare hosts that support leap seconds, SECOND may be 60. If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken to be zero). `am' indicates the first half of the day, `pm' indicates the second half of the day. In this notation, 12 is the predecessor of 1: midnight is `12am' while noon is `12pm'. (This is the zero-oriented interpretation of `12am' and `12pm', as opposed to the old tradition derived from Latin which uses `12m' for noon and `12pm' for midnight.) The time may alternatively be followed by a time zone correction, expressed as `SHHMM', where S is `+' or `-', HH is a number of zone hours and MM is a number of zone minutes. You can also separate HH from MM with a colon. When a time zone correction is given this way, it forces interpretation of the time relative to Coordinated Universal Time (UTC), overriding any previous specification for the time zone or the local time zone. For example, `+0530' and `+05:30' both stand for the time zone 5.5 hours ahead of UTC (e.g., India). The MINUTE part of the time of day may not be elided when a time zone correction is used. This is the best way to specify a time zone correction by fractional parts of an hour. Either `am'/`pm' or a time zone correction may be specified, but not both. 6.4 Time zone items =================== A "time zone item" specifies an international time zone, indicated by a small set of letters, e.g., `UTC' or `Z' for Coordinated Universal Time. Any included periods are ignored. By following a non-daylight-saving time zone by the string `DST' in a separate word (that is, separated by some white space), the corresponding daylight saving time zone may be specified. Alternatively, a non-daylight-saving time zone can be followed by a time zone correction, to add the two values. This is normally done only for `UTC'; for example, `UTC+05:30' is equivalent to `+05:30'. Time zone items other than `UTC' and `Z' are obsolescent and are not recommended, because they are ambiguous; for example, `EST' has a different meaning in Australia than in the United States. Instead, it's better to use unambiguous numeric time zone corrections like `-0500', as described in the previous section. If neither a time zone item nor a time zone correction is supplied, time stamps are interpreted using the rules of the default time zone (*note Specifying time zone rules::). 6.5 Day of week items ===================== The explicit mention of a day of the week will forward the date (only if necessary) to reach that day of the week in the future. Days of the week may be spelled out in full: `Sunday', `Monday', `Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'. Days may be abbreviated to their first three letters, optionally followed by a period. The special abbreviations `Tues' for `Tuesday', `Wednes' for `Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed. A number may precede a day of the week item to move forward supplementary weeks. It is best used in expression like `third monday'. In this context, `last DAY' or `next DAY' is also acceptable; they move one week before or after the day that DAY by itself would represent. A comma following a day of the week item is ignored. 6.6 Relative items in date strings ================================== "Relative items" adjust a date (or the current date if none) forward or backward. The effects of relative items accumulate. Here are some examples: 1 year 1 year ago 3 years 2 days The unit of time displacement may be selected by the string `year' or `month' for moving by whole years or months. These are fuzzy units, as years and months are not all of equal duration. More precise units are `fortnight' which is worth 14 days, `week' worth 7 days, `day' worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60 seconds, and `second' or `sec' worth one second. An `s' suffix on these units is accepted and ignored. The unit of time may be preceded by a multiplier, given as an optionally signed number. Unsigned numbers are taken as positively signed. No number at all implies 1 for a multiplier. Following a relative item by the string `ago' is equivalent to preceding the unit by a multiplier with value -1. The string `tomorrow' is worth one day in the future (equivalent to `day'), the string `yesterday' is worth one day in the past (equivalent to `day ago'). The strings `now' or `today' are relative items corresponding to zero-valued time displacement, these strings come from the fact a zero-valued time displacement represents the current time when not otherwise changed by previous items. They may be used to stress other items, like in `12:00 today'. The string `this' also has the meaning of a zero-valued time displacement, but is preferred in date strings like `this thursday'. When a relative item causes the resulting date to cross a boundary where the clocks were adjusted, typically for daylight saving time, the resulting date and time are adjusted accordingly. The fuzz in units can cause problems with relative items. For example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because 2003-06-31 is an invalid date. To determine the previous month more reliably, you can ask for the month before the 15th of the current month. For example: $ date -R Thu, 31 Jul 2003 13:02:39 -0700 $ date --date='-1 month' +'Last month was %B?' Last month was July? $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' Last month was June! Also, take care when manipulating dates around clock changes such as daylight saving leaps. In a few cases these have added or subtracted as much as 24 hours from the clock, so it is often wise to adopt universal time by setting the `TZ' environment variable to `UTC0' before embarking on calendrical calculations. 6.7 Pure numbers in date strings ================================ The precise interpretation of a pure decimal number depends on the context in the date string. If the decimal number is of the form YYYYMMDD and no other calendar date item (*note Calendar date items::) appears before it in the date string, then YYYY is read as the year, MM as the month number and DD as the day of the month, for the specified calendar date. If the decimal number is of the form HHMM and no other time of day item appears before it in the date string, then HH is read as the hour of the day and MM as the minute of the hour, for the specified time of day. MM can also be omitted. If both a calendar date and a time of day appear to the left of a number in the date string, but no relative item, then the number overrides the year. 6.8 Seconds since the Epoch =========================== If you precede a number with `@', it represents an internal time stamp as a count of seconds. The number can contain an internal decimal point (either `.' or `,'); any excess precision not supported by the internal representation is truncated toward minus infinity. Such a number cannot be combined with any other date item, as it specifies a complete time stamp. Internally, computer times are represented as a count of seconds since an epoch--a well-defined point of time. On GNU and POSIX systems, the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this time, `@1' represents 1970-01-01 00:00:01 UTC, and so forth. GNU and most other POSIX-compliant systems support such times as an extension to POSIX, using negative counts, so that `@-1' represents 1969-12-31 23:59:59 UTC. Traditional Unix systems count seconds with 32-bit two's-complement integers and can represent times from 1901-12-13 20:45:52 through 2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of seconds with nanosecond subcounts, and can represent all the times in the known lifetime of the universe to a resolution of 1 nanosecond. On most hosts, these counts ignore the presence of leap seconds. For example, on most hosts `@915148799' represents 1998-12-31 23:59:59 UTC, `@915148800' represents 1999-01-01 00:00:00 UTC, and there is no way to represent the intervening leap second 1998-12-31 23:59:60 UTC. 6.9 Specifying time zone rules ============================== Normally, dates are interpreted using the rules of the current time zone, which in turn are specified by the `TZ' environment variable, or by a system default if `TZ' is not set. To specify a different set of default time zone rules that apply just to one date, start the date with a string of the form `TZ="RULE"'. The two quote characters (`"') must be present in the date, and any quotes or backslashes within RULE must be escaped by a backslash. For example, with the GNU `date' command you can answer the question "What time is it in New York when a Paris clock shows 6:30am on October 31, 2004?" by using a date beginning with `TZ="Europe/Paris"' as shown in the following shell transcript: $ export TZ="America/New_York" $ date --date='TZ="Europe/Paris" 2004-10-31 06:30' Sun Oct 31 01:30:00 EDT 2004 In this example, the `--date' operand begins with its own `TZ' setting, so the rest of that operand is processed according to `Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it were in Paris. However, since the output of the `date' command is processed according to the overall time zone rules, it uses New York time. (Paris was normally six hours ahead of New York in 2004, but this example refers to a brief Halloween period when the gap was five hours.) A `TZ' value is a rule that typically names a location in the