berny/findutils
1
0
Fork 0
mirror of git://git.sv.gnu.org/findutils.git synced 2026-02-16 20:00:33 +01:00
Code Issues Packages Projects Releases Wiki Activity

Documentation improvements

Browse Source
This commit is contained in:
James Youngman
2007-04-09 23:13:57 +00:00
parent b5e99a0d08
commit f361af57cd
3 changed files with 140 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
ChangeLog
View File

@@ -1,3 +1,19 @@
2007-04-09 James Youngman <jay@gnu.org>
* doc/find.texi: Change fully-specified @node directives to
single-argument @node directives in order to accomodate the
inclusion of getdate.texi.
* doc/find.texi: Document -newerXY.
* doc/find.texi (Security Considerations): updated to describe
differences in the fts-based implementation.
* find/find.1: Indicate that testing the birth time where this is
not supported produces a negative result for files where the birth
time is not known (or a fatal error if the file of interest is a
reference file).
2007-04-08 James Youngman <jay@gnu.org>
* configure.in: Set @AUXDIR@ (to the location of the build-aux

163
doc/find.texi
View File

@@ -69,7 +69,8 @@ translation approved by the Foundation.
@contents
@ifnottex
@node Top, Introduction, , (dir)
@node Top
@top GNU Findutils
@comment node-name, next, previous, up
This file documents the GNU utilities for finding files that match
@@ -86,6 +87,7 @@ This is edition @value{EDITION}, for @code{find} version @value{VERSION}.
* Actions:: Doing things to files you have found.
* Databases:: Maintaining file name databases.
* File Permissions:: How to control access to files.
* Date input formats:: Specifying literal times.
* Reference:: Summary of how to invoke the programs.
* Common Tasks:: Solutions to common real-world problems.
* Worked Examples:: Examples demonstrating more complex points.
@@ -94,7 +96,7 @@ This is edition @value{EDITION}, for @code{find} version @value{VERSION}.
* Primary Index:: The components of @code{find} expressions.
@end menu
@node Introduction, Finding Files, Top, Top
@node Introduction
@chapter Introduction
This manual shows how to find files that meet criteria you specify,
@@ -331,7 +333,7 @@ for less than @var{n},
for exactly @var{n}.
@end table
@node Finding Files, Actions, Introduction, Top
@node Finding Files
@chapter Finding Files
By default, @code{find} prints to the standard output the names of the
@@ -778,7 +780,13 @@ change the status (modify the file or its attributes)
modify (change the file's contents)
@end enumerate
There is no timestamp that indicates when a file was @emph{created}.
Some systems also provide a timestamp that indicates when a file was
@emph{created}. For example, the UFS2 fileystem under NetBSD-3.1
records the @emph{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.
@@ -826,7 +834,7 @@ ago. So, to list the regular files in your home directory that were
modified yesterday, do
@example
find ~ -daystart -type f -mtime 1
find ~/ -daystart -type f -mtime 1
@end example
The @samp{-daystart} option is unlike most other options in that it
@@ -840,12 +848,56 @@ command line.
@node Comparing Timestamps
@subsection Comparing Timestamps
As an alternative to comparing timestamps to the current time, you can
compare them to another file's timestamp. That file's timestamp could
be updated by another program when some event occurs. Or you could
set it to a particular fixed date using the @code{touch} command. For
example, to list files in @file{/usr} modified after February 1 of the
current year:
@deffn Test -newerXY reference
Succeeds if timestamp @samp{X} of the file being considered is newer
than timestamp @samp{Y} of the file @file{reference}. The latters
@samp{X} and @samp{Y} can be any of the following letters:
@table @samp
@item a
Last-access time of @file{reference}
@item B
Birth time of @file{reference} (when this is not known, the test cannot succeed)
@item c
Last-change time of @file{reference}
@item m
Last-modification time of @file{reference}
@item t
The @file{reference} argument is interpreted as a literal time, rather
than the name of a file. @xref{Date input formats}, for a description
of how the timestamp is understood. Tests of the form @samp{-newerXt}
are valid but tests of the form @samp{-newertY} are not.
@end table
For example the test @code{-newerac /tmp/foo} succeeds for all files
which have been accessed more recently than @file{/tmp/foo} was
changed. Here @samp{X} is @samp{a} and @samp{Y} is @samp{c}.
Not all files have a known birth time. If @samp{Y} is @samp{b} and
the birth time of @file{reference} is not available, @code{find} exits
with an explanatory error message. If @samp{X} is @samp{b} and we do
not know the birth time the file currently being considered, the test
simply fails (that is, it behaves like @code{-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.
@end deffn
There are two ways to list files in @file{/usr} modified after
February 1 of the current year. One uses @samp{-newermt}:
@example
find /usr -newermt "Feb 1"
@end example
The other way of doing this works on the versions of find before 4.3.3:
@c Idea from Rick Sladkey.
@example
@@ -1390,7 +1442,7 @@ Always true.
Always false.
@end deffn
@node Actions, Databases, Finding Files, Top
@node Actions
@chapter Actions
There are several ways you can print information about the files that
@@ -2471,7 +2523,7 @@ find /usr/local -type f -perm /a=x \
@end example
@node Databases, File Permissions, Actions, Top
@node Databases
@chapter File Name Databases
The file name databases used by @code{locate} contain lists of files
@@ -2676,12 +2728,14 @@ So, if you are using the new database format (this is the default) and
your system uses GNU @code{sort}, newlines will be correctly handled
at all times. Otherwise, newlines may not be correctly handled.
@node File Permissions, Reference, Databases, Top
@node File Permissions
@chapter File Permissions
@include perm.texi
@node Reference, Common Tasks, File Permissions, Top
@include getdate.texi
@node Reference
@chapter Reference
Below are summaries of the command line syntax for the programs
@@ -2696,7 +2750,7 @@ discussed in this manual.
* Environment Variables::
@end menu
@node Invoking find, Invoking locate, , Reference
@node Invoking find
@section Invoking @code{find}
@example
@@ -2745,7 +2799,7 @@ The @samp{-version} option is a synonym for @samp{--version}
* Find Expressions::
@end menu
@node Filesystem Traversal Options, Warning Messages,, Invoking find
@node Filesystem Traversal Options
@subsection Filesystem Traversal Options
The options @samp{-H}, @samp{-L} or @samp{-P} may be specified at the
@@ -2772,7 +2826,7 @@ broken), it falls back on using the properties of the symbolic link
itself. @ref{Symbolic Links} for a more complete description of how
symbolic links are handled.
@node Warning Messages, Optimisation Options, Filesystem Traversal Options, Invoking find
@node Warning Messages
@subsection Warning Messages
If there is an error on the @code{find} command line, an error message
@@ -2822,7 +2876,7 @@ Use of an unrecognised backslash escape sequence with @samp{-fprintf}
Use of an unrecognised formatting directive with @samp{-fprintf}
@end itemize
@node Optimisation Options, Debug Options, Warning Messages, Invoking find
@node Optimisation Options
@subsection Optimisation Options
The @samp{-O@var{level}} option sets @code{find}'s optimisation level
@@ -2862,7 +2916,7 @@ evaluated earlier.
@end table
@node Debug Options, Find Expressions, Optimisation Options, Invoking find
@node Debug Options
@subsection Debug Options
The @samp{-D} option makes @code{find} produce diagnostic output.
@@ -2886,7 +2940,7 @@ Prints diagnostic information relating to the optimisation of the
expression tree; see the @samp{-O} option.
@end table
@node Find Expressions,, Debug Options, Invoking find
@node Find Expressions
@subsection Find Expressions
The final part of the @code{find} command line is a list of
@@ -2894,7 +2948,7 @@ expressions. @xref{Primary Index}, for a summary of all of the tests,
actions, and options that the expression can contain. If the
expression is missing, @samp{-print} is assumed.
@node Invoking locate, Invoking updatedb, Invoking find, Reference
@node Invoking locate
@section Invoking @code{locate}
@example
@@ -3055,7 +3109,7 @@ Print a summary of the command line usage for @code{locate} and exit.
Print the version number of @code{locate} and exit.
@end table
@node Invoking updatedb, Invoking xargs, Invoking locate, Reference
@node Invoking updatedb
@section Invoking @code{updatedb}
@example
@@ -3140,7 +3194,7 @@ Print a summary of the command line usage and exit.
Print the version number of @code{updatedb} and exit.
@end table
@node Invoking xargs, Regular Expressions, Invoking updatedb, Reference
@node Invoking xargs
@section Invoking @code{xargs}
@example
@@ -3289,7 +3343,7 @@ possible simultaneously.
@end table
@node Regular Expressions, Environment Variables, Invoking xargs, Reference
@node Regular Expressions
@section Regular Expressions
The @samp{-regex} and @samp{-iregex} tests of @code{find} allow
@@ -3307,7 +3361,7 @@ should be one of the following:
@include regexprops.texi
@node Environment Variables,, Regular Expressions, Reference
@node Environment Variables
@section Environment Variables
@table @var
@item LANG
@@ -3354,7 +3408,7 @@ directives of @samp{-printf} and @samp{-fprintf}.
@node Common Tasks, Worked Examples, Reference, Top
@node Common Tasks
@chapter Common Tasks
The sections that follow contain some extended examples that both give
@@ -3609,7 +3663,7 @@ cat allexec
@code{find} has only to make one scan through the directory tree
(which is one of the most time consuming parts of its work).
@node Worked Examples, Security Considerations, Common Tasks, Top
@node Worked Examples
@chapter Worked Examples
The tools in the findutils package, and in particular @code{find},
@@ -4150,7 +4204,7 @@ other, to the nearest second. The second @code{find} command takes
each resulting file one at a time, and if that is newer than the
timestamp file, the timestamp is updated.
@node Security Considerations, Error Messages, Worked Examples, Top
@node Security Considerations
@chapter Security Considerations
Security considerations are important if you are using @code{find} or
@@ -4304,6 +4358,7 @@ However, your degree of safety does depend on the nature of the
program you are running. For example constructs such as these two commands
@example
# risky
find -exec sh -c "something @{@}" \;
find -execdir sh -c "something @{@}" \;
@end example
@@ -4319,6 +4374,19 @@ data (such as the names of files) to commands which interpret
arguments as commands to be further interpreted (for example
@samp{sh}).
In the case of the shell, there is a clever workaround for this
problem:
@example
# safer
find -exec sh -c 'something "$@@"' @{@} \;
find -execdir sh -c 'something "$@@"' @{@}\;
@end example
This approach is not guaranteed to avoid every problem, but it is much
safer than substituting data of an attacker's choice into the text of
a shell command.
@node Changing the Current Working Directory
@subsection Changing the Current Working Directory
@@ -4415,7 +4483,8 @@ fail.
However, this does not normally represent a security problem, since
the automounter configuration is normally set up by the system
administrator. Therefore, if the @code{chdir()} sanity check fails,
@code{find} will make one more attempt. If that succeeds, execution
@code{find} will make one more attempt@footnote{This may not be the
case for the fts-based executable}. If that succeeds, execution
carries on as normal. This is the usual case for automounters.
Where an attacker is trying to exploit a race condition, the problem
@@ -4552,6 +4621,14 @@ ensures that @code{xargs} considers file names to be separated by
ASCII NUL characters rather than whitespace. However, useful as this
option is, the POSIX standard does not make it mandatory.
POSIX also specifies that @code{xargs} interprets quoting and trailing
whitespace specially in filenames, too. This means that using
@code{find ... -print | xargs ...} can cause the commands run by
@code{xargs} to receive a list of file names which is not the same as
the list printed by @code{find}. The interpretation of quotes and
trailing whitespace is turned off by the @samp{-0} argument to
@code{xargs}, which is another reason to use that option.
@comment node-name, next, previous, up
@node Security Considerations for locate
@section Security Considerations for @code{locate}
@@ -4588,7 +4665,7 @@ only trusted programs.
@end table
@comment node-name, next, previous, up
@node Error Messages, Primary Index, Security Considerations, Top
@node Error Messages
@chapter Error Messages
This section describes some of the error messages sometimes made by
@@ -4597,13 +4674,13 @@ cases provides advice as to what you should do about this.
This manual is written in English. The GNU findutils software
features translations of error messages for many languages. For this
reason the error messages produced by
the programs are made to be as self-explanatory as possible. This approach avoids leaving people to
figure out which test an English-language error message
corresponds to. Error messages which are self-explanatory
will not normally be mentioned in this document. For
those messages mentioned in this document, only the
English-language version of the message will be listed.
reason the error messages produced by the programs are made to be as
self-explanatory as possible. This approach avoids leaving people to
figure out which test an English-language error message corresponds
to. Error messages which are self-explanatory will not normally be
mentioned in this document. For those messages mentioned in this
document, only the English-language version of the message will be
listed.
@menu
* Error Messages From find::
@@ -4612,7 +4689,7 @@ English-language version of the message will be listed.
* Error Messages From updatedb::
@end menu
@node Error Messages From find, Error Messages From xargs, , Error Messages
@node Error Messages From find
@section Error Messages From @code{find}
@table @samp
@@ -4699,7 +4776,7 @@ with a fatal signal. This is just an advisory message.
@end table
@node Error Messages From xargs, Error Messages From locate, Error Messages From find, Error Messages
@node Error Messages From xargs
@section Error Messages From xargs
@table @samp
@@ -4735,7 +4812,7 @@ return status 255.
See the description of the similar message for @code{find}.
@end table
@node Error Messages From locate, Error Messages From updatedb, Error Messages From xargs, Error Messages
@node Error Messages From locate
@section Error Messages From @code{locate}
@table @samp
@@ -4759,7 +4836,7 @@ these programs should interoperate without problem. Ask for help on
@end table
@node Error Messages From updatedb, , Error Messages From locate, Error Messages
@node Error Messages From updatedb
@section Error Messages From updatedb
The @code{updatedb} program (and the programs it invokes) do issue
@@ -4768,7 +4845,7 @@ you are having a problem understanding one of these, ask for help on
@email{bug-findutils@@gnu.org}.
@node Primary Index, , Error Messages, Top
@node Primary Index
@unnumbered @code{find} Primary Index
This is a list of all of the primaries (tests, actions, and options)

4
find/find.1
View File

@@ -477,6 +477,10 @@ combination of
is specified, a fatal error results. Time specifications are
interpreted as for the argument to the \-d option of GNU
.BR date .
If you try to use the birth time of a reference file, and the birth
time cannot be determined, a fatal error message results. If you
specify a test which refers to the birth time of files being examined,
this test will fail for any files where the birth time is unknown.
.IP \-nouser
No user corresponds to file's numeric user ID.
.IP \-nogroup