Package: findutils
Version: upstream (git)
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man
page"
[Use "groff -e ' $' -e '\\~$' <file>" to find obvious trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
an.tmac:<stdin>:2: style: .TH missing third argument; consider document
modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:<stdin>:2: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.12-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages findutils depends on:
ii libc6 2.40-7
ii libselinux1 3.8-4
findutils recommends no packages.
findutils suggests no packages.
-- no debconf information
Input file is find.1
Output from "mandoc -T lint find.1": (shortened list)
1 input text line longer than 80 bytes: Some of the conversi...
1 missing date, using "": TH
1 unterminated quoted argument
-.-.
Output from "test-nroff -mandoc -t -ww -z find.1": (shortened list)
1 Use macro '.B' for one argument or split argument.
1 Use macro '.I' for one argument or split argument.
1 .BR is for at least 2 arguments, got 1
1 .IR is for at least 2 arguments, got 1
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
73:until an expression argument comes (which also starts with a `-').
74:Now, if a path argument would start with a `-', then
875:An exception to this is when using only a slash as \fIpattern\fR (`-name
/'),
878:A warning is issued if you try to pass a pattern containing a - but not
879:consisting solely of one - slash, unless the environment variable
1095:The + and - prefixes signify greater than and less than, as usual;
1832:find / -name needle -print -quit
2252:.SS Safer `find -print0 | xargs -0` approach
2324:.SS Traversing the filesystem just once - for 2 different actions
2473:Pruning - omitting files and subdirectories
2590:.B $ find / -name needle -print -quit
2607:.B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0
-printf '[%h][%f]\en'
2654:.B find -print0
2656:.B xargs -0
2743:find: possible unquoted pattern after predicate `-name'?
-.-.
Add a "\&" (or a comma (Oxford comma)) after "e.g." and "i.e.",
or use English words
(man-pages(7)).
Abbreviation points should be marked as such and protected against being
interpreted as an end of sentence, if they are not, and that independent
of the current place on the line.
546:and e.g. from a pipe.
565:The processing of the starting points is otherwise as usual, e.g.
-.-.
Wrong distance (not two spaces) between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
[List of affected lines removed.]
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
Line 1546, length 86
Some of the conversion specification characters might not be available on all
systems,
Line 2487, length 82
.B $ find . \-name .snapshot \-prune \-o \e( \e! \-name \(aq*~\(aq \-print0 \e)
\e
Line 2607, length 96
.B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0
-printf '[%h][%f]\en'
Line 2645, length 87
.I A Research UNIX Reader: Annotated Excerpts from the Programmerâs Manual,
1971-1986
-.-.
Use \(en (en-dash) for a dash at the beginning (end) of a line,
or between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
find.1:2324:.SS Traversing the filesystem just once - for 2 different actions
find.1:2473:Pruning - omitting files and subdirectories
-.-.
Remove reverse slash (\) in front of a period (.) that is to be printed
as such, and can not come a control character in the first column of a line.
Use "\&" to protect the period to avoid that.
This is a sign, that the man page was transformed from another source
file with a program, whose name is NOT mentioned in a comment.
2715:\.B \-perm +MODE
2717:\.B \-perm
-.-.
Split a punctuation mark from a single argument for a two-font macro
1048:.IR ./fubar3,
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
[List of affected lines removed.]
-.-.
One space only after an end of sentence.
find.1:339:no error message will be issued. This is the reason why such
operation
find.1:546:and e.g. from a pipe.
find.1:960:find . \-path \(dq./sr*sc\(dq
find.1:1797:find . \-path ./src/emacs \-prune \-o \-print
find.1:1896:.B find . \-name afile \-o \-name bfile \-print
find.1:2309:.B $ find . \-type f \-exec file \(aq{}\(aq \e;
find.1:2384:.B $ find . \-perm 664
find.1:2399:.B $ find . \-perm \-664
find.1:2413:.B $ find . \-perm /222
find.1:2423:.B $ find . \-perm /220
find.1:2424:.B $ find . \-perm /u+w,g+w
find.1:2425:.B $ find . \-perm /u=w,g=w
find.1:2440:.B $ find . \-perm \-220
find.1:2441:.B $ find . \-perm \-g+w,u+w
find.1:2452:.B $ find . \-perm \-444 \-perm /222 \e! \-perm /111
find.1:2453:.B $ find . \-perm \-a+r \-perm /a+w \e! \-perm /a+x
find.1:2467:.RB ( "! \-perm /111"
find.1:2469:.B ! \-perm /a+x
find.1:2487:.B $ find . \-name .snapshot \-prune \-o \e( \e! \-name \(aq*~\(aq
\-print0 \e) \e
find.1:2607:.B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find
-maxdepth 0 -printf '[%h][%f]\en'
find.1:2727:.B find . \-name afile \-o \-name bfile \-print
find.1:2731:.BR "find . \-name afile \-o \e( \-name bfile \-a \-print \e)" .
find.1:2741:.B $ find . \-name *.c \-print
find.1:2754:.B find . \-name frcode.c locate.c word_io.c \-print
find.1:2766:.B $ find . \-name \(aq*.c\(aq \-print
find.1:2767:.B $ find . \-name \e*.c \-print
-.-.
Put a subordinate sentence (after a comma) on a new line.
[List of affected lines removed.]
-.-.
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
find.1:638:.IP "\-noleaf"
find.1:1154:.IP "\-writable"
find.1:1196:.IP "\-delete\fR"
find.1:1802:.IP "\-quit"
find.1:2233:.SH "EXAMPLES"
find.1:2638:.SH "HISTORY"
find.1:2659:.SH "COMPATIBILITY"
find.1:2724:.SH "NON-BUGS"
find.1:2770:.SH "BUGS"
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
1968:.SH "STANDARDS CONFORMANCE"
2120:.SH "ENVIRONMENT VARIABLES"
2233:.SH "EXAMPLES"
2638:.SH "HISTORY"
2659:.SH "COMPATIBILITY"
2724:.SH "NON-BUGS"
2770:.SH "BUGS"
2788:.SH "REPORTING BUGS"
2811:.SH "SEE ALSO"
-.-.
Space after an end of sentence.
temp.table:25:\-exec ... + 4.2.12 POSIX
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:2: style: .TH missing third argument; consider document
modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:<stdin>:2: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
an.tmac:<stdin>:690: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
an.tmac:<stdin>:1048: misuse, warning: .IR is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument.
-.-.
Additionally:
Change "1\ KB" to "1\ KiB"
Change indent "4m" to "4n". "4m" is too wide in troff-mode.
Inhibit hyphenation of "strftime" once (based on an A4 page size).
Create a "space" between some tags and the its following text by adding
" \&" to the tag.
Decrease indent after a bullet in lists.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- find.1 2025-03-07 20:55:57.739825277 +0000
+++ find.1.new 2025-03-08 13:48:25.945936075 +0000
@@ -4,8 +4,9 @@
find \- search for files in a directory hierarchy
.SH SYNOPSIS
.B find
-[\-H] [\-L] [\-P] [\-D debugopts] [\-Olevel] [starting-point...\&] [expression]
-.
+[\-H] [\-L] [\-P] [\-D debugopts] [\-O\fIlevel\fP] [starting-point...\&] \
+[expression]
+ .
.SH DESCRIPTION
This manual page
documents the GNU version of
@@ -70,8 +71,8 @@ could theoretically be used to signal th
are not options, but this does not really work due to the way
.B find
determines the end of the following path arguments: it does that by reading
-until an expression argument comes (which also starts with a `-').
-Now, if a path argument would start with a `-', then
+until an expression argument comes (which also starts with a `\-').
+Now, if a path argument would start with a `\-', then
.B find
would treat it as expression argument instead.
Thus, to ensure that all start points are taken as such, and especially to
@@ -259,7 +260,7 @@ Enable all of the other debug options (b
.IP help
Explain the debugging options.
.RE
-.IP \-Olevel
+.IP "\-O\fIlevel\fP \&"
Enables query optimisation.
The
.B find
@@ -336,8 +337,10 @@ predicates are sensitive to re-ordering.
an error message will be issued for unreadable directories. If they
are run in the order
.B \-readable \-empty
-no error message will be issued. This is the reason why such operation
-re-ordering is not performed at the default optimisation level.
+no error message will be issued.
+This is the reason
+why such operation re-ordering is not performed at the default
+optimisation level.
.
.SH EXPRESSION
The part of the command line after the list of starting points is the
@@ -431,7 +434,7 @@ and
from the beginning of today rather than from 24 hours ago. This
option only affects tests which appear later on the command line.
-.IP \-follow
+.IP "\-follow \&"
Deprecated; use the
.B \-L
option instead. Dereference symbolic links.
@@ -543,7 +546,7 @@ The \fIfile\fR argument is mandatory.
One can use
.B \-files0\-from\ \-
to read the list of starting points from the \fIstandard input\fR stream,
-and e.g. from a pipe.
+and e.g.\& from a pipe.
In this case, the actions
.B \-ok
and
@@ -562,7 +565,7 @@ arguments.
This is unlike the standard invocation where \fBfind\fR assumes the current
directory as starting point if no path argument is passed.
-The processing of the starting points is otherwise as usual, e.g.
+The processing of the starting points is otherwise as usual, e.g.\&
.B find
will recurse into subdirectories unless otherwise prevented.
To process only the starting points, one can additionally pass
@@ -635,7 +638,7 @@ for compatibility with some other versio
Turns off the effect of
.BR \-ignore_readdir_race .
-.IP "\-noleaf"
+.IP "\-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
@@ -687,7 +690,7 @@ A numeric argument \fIn\fR can be specif
.BR \-inum ,
.BR \-links ,
.BR \-size ,
-.BR \-uid
+.B \-uid
and
.BR \-used )
as
@@ -704,7 +707,7 @@ for exactly
.P
Supported tests:
-.IP "\-amin \fIn\fR"
+.IP "\-amin \fIn\fR \&"
File was last accessed less than, more than or exactly \fIn\fR minutes ago.
.IP "\-anewer \fIreference\fR"
@@ -730,7 +733,7 @@ a file has to have been accessed at leas
.I two
days ago.
-.IP "\-cmin \fIn\fR"
+.IP "\-cmin \fIn\fR \&"
File's status was last changed less than, more than or exactly \fIn\fR minutes
ago.
@@ -814,7 +817,7 @@ patterns `fo*' and `F??' match the file
`fOo', etc.
The pattern `*foo*` will also match a file called '.foobar'.
-.IP "\-inum \fIn\fR"
+.IP "\-inum \fIn\fR \&"
File has inode number smaller than, greater than or exactly
.IR n .
It is normally easier to use the
@@ -849,7 +852,7 @@ option or the
option is in effect, this test returns false unless the symbolic link
is broken.
-.IP "\-mmin \fIn\fR"
+.IP "\-mmin \fIn\fR \&"
File's data was last modified less than, more than or exactly \fIn\fR minutes
ago.
@@ -872,11 +875,11 @@ should not include a slash, because `\-n
(and you probably want to use
.B \-path
instead).
-An exception to this is when using only a slash as \fIpattern\fR (`-name /'),
+An exception to this is when using only a slash as \fIpattern\fR (`\-name /'),
because that is a valid string for matching the root directory "/" (because the
base name of "/" is "/").
-A warning is issued if you try to pass a pattern containing a - but not
-consisting solely of one - slash, unless the environment variable
+A warning is issued if you try to pass a pattern containing a \- but not
+consisting solely of one \- slash, unless the environment variable
.B POSIXLY_CORRECT
is set or the option
.B \-nowarn
@@ -955,9 +958,9 @@ File name matches shell pattern
.IR pattern .
The metacharacters do not treat `/' or `.\&' specially;
so, for example,
-.in +4m
+.in +4n
.nf
-find . \-path \(dq./sr*sc\(dq
+find .\& \-path \(dq./sr*sc\(dq
.fi
.in
will print an entry for a directory called
@@ -972,7 +975,7 @@ would only make sense to use an absolute
relevant start point is also an absolute path. This means that this
command will never match anything:
.br
-.in +4m
+.in +4n
.nf
find bar \-path /foo/bar/myfile \-print
.fi
@@ -1045,7 +1048,7 @@ File name matches regular expression
.IR pattern .
This is a match on the whole path, not a search.
For example, to match a file named
-.IR ./fubar3,
+.IR ./fubar3 ,
you can use the regular expression `.*bar.\&' or `.*b.*3',
but not `f.*r3'.
The regular expressions understood by
@@ -1092,7 +1095,7 @@ differently. The `b' suffix always deno
1024-byte blocks, which is different to the behaviour of
.BR \-ls .
.IP
-The + and - prefixes signify greater than and less than, as usual;
+The + and \- prefixes signify greater than and less than, as usual;
i.e., an exact size of \fIn\fR units does not match.
Bear in mind that the size is rounded up to the next unit.
Therefore
@@ -1104,7 +1107,7 @@ The former only matches empty files, the
.IP \-true
Always true.
-.IP "\-type \fIc\fR"
+.IP "\-type \fIc\fR \&"
File is of type
.IR c :
.RS
@@ -1140,7 +1143,7 @@ type letters separated by a comma `,' (G
File's numeric user ID is less than, more than or exactly
.IR n .
-.IP "\-used \fIn\fR"
+.IP "\-used \fIn\fR \&"
File was last accessed less than, more than or exactly \fIn\fR days after its
status was last changed.
@@ -1151,7 +1154,7 @@ File is owned by user \fIuname\fR (numer
See \-path. This alternative is less portable than
.BR \-path .
-.IP "\-writable"
+.IP \-writable
Matches files which are writable by the current user. This takes into
account access control lists and other permissions artefacts which the
.B \-perm
@@ -1193,7 +1196,7 @@ will behave the same as
.IR pattern .
.SS ACTIONS
-.IP "\-delete\fR"
+.IP "\-delete \&"
Delete files or directories; true if removal succeeded.
If the removal failed, an error message is issued and
.BR find 's
@@ -1410,7 +1413,7 @@ section for information about how unusua
True; list current file in
.B ls \-dils
format on standard output.
-The block counts are of 1\ KB blocks, unless the environment variable
+The block counts are of 1\ KiB blocks, unless the environment variable
.B POSIXLY_CORRECT
is set, in which case 512-byte blocks are used.
See the
@@ -1476,7 +1479,7 @@ See the
.B UNUSUAL FILENAMES
section for information about how unusual characters in filenames are handled.
-.IP \-print0
+.IP "\-print0 \&"
True; print the full file name on the standard output, followed by a
null character (instead of the newline character that
.B \-print
@@ -1543,7 +1546,8 @@ The following shows an incomplete list o
Please refer to the documentation of
.BR strftime (3)
for the full list.
-Some of the conversion specification characters might not be available on all
systems,
+Some of the conversion specification characters might not be available on
+all systems,
due to differences in the implementation of the
.BR strftime (3)
library function.
@@ -1677,7 +1681,7 @@ Starting-point under which file was foun
.IP %i
File's inode number (in decimal).
.IP %k
-The amount of disk space used for this file in 1\ KB blocks.
+The amount of disk space used for this file in 1\ KiB 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.
@@ -1792,14 +1796,14 @@ For example, to skip the directory
.I src/emacs
and all files and directories under it, and print the names of the other files
found, do something like this:
-.in +4m
+.in +4n
.nf
-find . \-path ./src/emacs \-prune \-o \-print
+find .\& \-path ./src/emacs \-prune \-o \-print
.fi
.in
-.IP "\-quit"
+.IP \-quit
Exit immediately (with return value zero if no errors have occurred).
This is different to
.B \-prune
@@ -1827,9 +1831,9 @@ One common use of
is to stop searching the file system once we have
found what we want. For example, if we want to find just a single
file we can do this:
-.in +4m
+.in +4n
.nf
-find / -name needle -print -quit
+find / \-name needle \-print \-quit
.fi
.in
@@ -1893,7 +1897,7 @@ an explicit operator between them) or ex
than
.BR \-o .
This means that
-.B find . \-name afile \-o \-name bfile \-print
+.B find .\& \-name afile \-o \-name bfile \-print
will never print
.IR afile .
.
@@ -1965,7 +1969,7 @@ and
.B \-okdir
actions print the current filename as-is. This may change in a future release.
.
-.SH "STANDARDS CONFORMANCE"
+.SH STANDARDS CONFORMANCE
For closest compliance to the POSIX standard, you should set the
.B POSIXLY_CORRECT
environment variable.
@@ -2117,7 +2121,7 @@ or
.B \-iregex
tests because those tests aren't specified in the POSIX standard.
.
-.SH "ENVIRONMENT VARIABLES"
+.SH ENVIRONMENT VARIABLES
.IP LANG
Provides a default value for the internationalization variables that
@@ -2172,7 +2176,7 @@ the response to the prompt made by the
.B \-ok
action.
-.IP NLSPATH
+.IP "NLSPATH \&"
Determines the location of the internationalisation message catalogues.
.IP PATH
@@ -2230,10 +2234,15 @@ directives of
and
.BR \-fprintf .
.
-.SH "EXAMPLES"
+.SH EXAMPLES
.\" A bulleted \[bu] list of examples.
.SS Simple `find|xargs` approach
-.IP \[bu]
+.\.".nr margin_n \n[an-margin]u/1n
+.\"an-margin is \n[margin_n]n
+.\".nr prev-indent_n \n[an-prevailing-indent]u/1n
+.\"an-prevailing-indent] is \n[prev-indent_n]n
+.\".br
+.IP \[bu] 4n
Find files named
.I core
in or below the directory
@@ -2241,7 +2250,7 @@ in or below the directory
and delete them.
.nf
\&
-.in +4m
+.in +4n
.B $ find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
.in
\&
@@ -2249,15 +2258,15 @@ and delete them.
Note that this will work incorrectly if there are
any filenames containing newlines, single or double quotes, or spaces.
.
-.SS Safer `find -print0 | xargs -0` approach
-.IP \[bu]
+.SS Safer `find \-print0 | xargs \-0` approach
+.IP \[bu] 4n
Find files named \fIcore\fP in or below the directory \fI/tmp\fP
and delete them, processing filenames in such a way that file or
directory names containing single or double quotes, spaces or newlines
are correctly handled.
.nf
\&
-.in +4m
+.in +4n
.B $ find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
.in
\&
@@ -2278,13 +2287,13 @@ process executed by
works with that file.
.
.SS Processing arbitrary starting points
-.IP \[bu]
+.IP \[bu] 4n
Given that another program \fIproggy\fR pre-filters and creates a huge
NUL-separated list of files, process those as starting points, and find
all regular, empty files among them:
.nf
\&
-.in +4m
+.in +4n
.B $ proggy | find \-files0\-from \- \-maxdepth 0 \-type f \-empty
.in
\&
@@ -2299,14 +2308,14 @@ into directories (in the case one of the
.
.SS
Executing a command for each file
-.IP \[bu]
+.IP \[bu] 4n
Run
.I file
on every file in or below the current directory.
.nf
\&
-.in +4m
-.B $ find . \-type f \-exec file \(aq{}\(aq \e;
+.in +4n
+.B $ find .\& \-type f \-exec file \(aq{}\(aq \e;
.in
\&
.fi
@@ -2321,8 +2330,8 @@ or better the
.B `\-execdir\ \&...\&\ +`
syntax for performance and security reasons.
.
-.SS Traversing the filesystem just once - for 2 different actions
-.IP \[bu]
+.SS Traversing the filesystem just once \(en for 2 different actions
+.IP \[bu] 4n
Traverse the filesystem just once, listing set-user-ID files and
directories into
.I /root/suid.txt
@@ -2330,14 +2339,14 @@ and large files into
.IR /root/big.txt .
.nf
\&
-.in +4m
+.in +4n
.B $ find / \e
-.in +4m
+.in +4n
.B \e( \-perm \-4000 \-fprintf /root/suid.txt \(aq%#m %u %p\en\(aq \e) , \e
.br
.B \e( \-size +100M \-fprintf /root/big.txt \(aq%\-10s %p\en\(aq \e)
-.in -4m
-.in -4m
+.in -4n
+.in -4n
\&
.fi
This example uses the line-continuation character \(aq\e\(aq on the first two
@@ -2345,12 +2354,12 @@ lines to instruct the shell to continue
.
.SS
Searching files by age
-.IP \[bu]
+.IP \[bu] 4n
Search for files in your home directory which have been modified in
the last twenty-four hours.
.nf
\&
-.in +4m
+.in +4n
.B $ find $HOME \-mtime 0
.in
\&
@@ -2365,23 +2374,23 @@ a file will have to have a modification
.
.SS
Searching files by permissions
-.IP \[bu]
+.IP \[bu] 4n
Search for files which are executable but not readable.
.nf
\&
-.in +4m
+.in +4n
.B $ find /sbin /usr/sbin \-executable \e! \-readable \-print
.in
\&
.fi
.
-.IP \[bu]
+.IP \[bu] 4n
Search for files which have read and write permission for their owner,
and group, but which other users can read but not write to.
.nf
\&
-.in +4m
-.B $ find . \-perm 664
+.in +4n
+.B $ find .\& \-perm 664
.in
\&
.fi
@@ -2395,8 +2404,8 @@ presence of any extra permission bits (f
bit).
.nf
\&
-.in +4m
-.B $ find . \-perm \-664
+.in +4n
+.B $ find .\& \-perm \-664
.in
\&
.fi
@@ -2409,8 +2418,8 @@ Search for files which are writable by s
their group, or anybody else).
.nf
\&
-.in +4m
-.B $ find . \-perm /222
+.in +4n
+.B $ find .\& \-perm /222
.in
\&
.fi
@@ -2419,10 +2428,10 @@ their group, or anybody else).
Search for files which are writable by either their owner or their group.
.nf
\&
-.in +4m
-.B $ find . \-perm /220
-.B $ find . \-perm /u+w,g+w
-.B $ find . \-perm /u=w,g=w
+.in +4n
+.B $ find .\& \-perm /220
+.B $ find .\& \-perm /u+w,g+w
+.B $ find .\& \-perm /u=w,g=w
.in
\&
.fi
@@ -2436,9 +2445,9 @@ either will do.
Search for files which are writable by both their owner and their group.
.nf
\&
-.in +4m
-.B $ find . \-perm \-220
-.B $ find . \-perm \-g+w,u+w
+.in +4n
+.B $ find .\& \-perm \-220
+.B $ find .\& \-perm \-g+w,u+w
.in
\&
.fi
@@ -2448,9 +2457,9 @@ Both these commands do the same thing.
A more elaborate search on permissions.
.nf
\&
-.in +4m
-.B $ find . \-perm \-444 \-perm /222 \e! \-perm /111
-.B $ find . \-perm \-a+r \-perm /a+w \e! \-perm /a+x
+.in +4n
+.B $ find .\& \-perm \-444 \-perm /222 \e! \-perm /111
+.B $ find .\& \-perm \-a+r \-perm /a+w \e! \-perm /a+x
.in
\&
.fi
@@ -2464,14 +2473,14 @@ set
or
.BR "\-perm /a+w" )
but are not executable for anybody
-.RB ( "! \-perm /111"
+.RB ( "!\& \-perm /111"
or
-.B ! \-perm /a+x
+.B !\& \-perm /a+x
respectively).
.
.SS
-Pruning - omitting files and subdirectories
-.IP \[bu]
+Pruning \(en omitting files and subdirectories
+.IP \[bu] 4n
Copy the contents of
.I /source-dir
to
@@ -2482,14 +2491,14 @@ but omit files and directories named
`\(ti', but not their contents.
.nf
\&
-.in +4m
+.in +4n
.B $ cd /source-dir
-.B $ find . \-name .snapshot \-prune \-o \e( \e! \-name \(aq*~\(aq \-print0
\e) \e
+.B $ find .\& \-name .snapshot \-prune \-o \e( \e! \-name \(aq*~\(aq \-print0
\e) \e
.br
-.in +4m
+.in +4n
.B | cpio \-pmd0 /dest-dir
-.in -4m
-.in -4m
+.in -4n
+.in -4n
\&
.fi
The construct
@@ -2515,27 +2524,27 @@ binds more tightly than
this is the default anyway, but the parentheses help to show
what is going on.
.
-.IP \[bu]
+.IP \[bu] 4n
Given the following directory of projects and their associated SCM
administrative directories, perform an efficient search for the
projects' roots:
.nf
\&
-.in +4m
+.in +4n
.B $ find repo/ \e
-.in +4m
+.in +4n
.B \e( \-exec test \-d \(aq{}/.svn\(aq \e; \e
.B \-or \-exec test \-d \(aq{}/.git\(aq \e; \e
.B \-or \-exec test \-d \(aq{}/CVS\(aq \e; \e
.B \e) \-print \-prune
-.in -4m
-.in -4m
+.in -4n
+.in -4n
\&
.fi
Sample output:
.nf
\&
-.in +4m
+.in +4n
.B repo/project1/CVS
.B repo/gnu/project2/.svn
.B repo/gnu/project3/.svn
@@ -2559,11 +2568,11 @@ are found.
.
.SS
Other useful examples
-.IP \[bu]
+.IP \[bu] 4n
Search for several file types.
.nf
\&
-.in +4m
+.in +4n
.B $ find /tmp \-type f,d,l
.in
\&
@@ -2574,25 +2583,25 @@ passing these types as a comma-separated
which is otherwise equivalent to the longer, yet more portable:
.nf
\&
-.in +4m
+.in +4n
.B $ find /tmp \e( \-type f \-o \-type d \-o \-type l \e)
.in
\&
.fi
.
-.IP \[bu]
+.IP \[bu] 4n
Search for files with the particular name
.I needle
and stop immediately when we find the first one.
.nf
\&
-.in +4m
-.B $ find / -name needle -print -quit
+.in +4n
+.B $ find / \-name needle \-print \-quit
.in
\&
.fi
.
-.IP \[bu]
+.IP \[bu] 4n
Demonstrate the interpretation of the
.B %f
and
@@ -2603,8 +2612,9 @@ action for some corner-cases.
Here is an example including some output.
.nf
\&
-.in +4m
-.B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0
-printf '[%h][%f]\en'
+.in +4n
+.B $ find .\& .. / /tmp /tmp/TRACE compile compile/64/tests/find \e
+.B " \-maxdepth 0 \-printf '[%h][%f]\en'"
.B [.][.]
.B [.][..]
.B [][/]
@@ -2632,17 +2642,18 @@ For example, some starting points may no
pending program invocations for
.B \-exec\ \&...\&\ {}\ +
or
-.B "\-execdir\ \&...\&\ {}\ +
+.B \-execdir\ \&...\&\ {}\ +
may not have been performed.
.
-.SH "HISTORY"
+.SH HISTORY
A
.B find
program appeared in Version 5 Unix as part of the
Programmer's Workbench project and was written by Dick Haight. Doug
McIlroy's
-.I A Research UNIX Reader: Annotated Excerpts from the Programmerâs Manual,
1971-1986
+.I A Research UNIX Reader: Annotated Excerpts from the Programmerâs \
+Manual, 1971\(en1986
provides some additional details; you can read it on-line at
<https://www.cs.dartmouth.edu/~doug/reader.pdf>.
@@ -2651,12 +2662,12 @@ GNU
was originally written by Eric Decker, with
enhancements by David MacKenzie, Jay Plett, and Tim Wood. The idea
for
-.B find -print0
+.B find \-print0
and
-.B xargs -0
+.B xargs \-0
came from Dan Bernstein.
.
-.SH "COMPATIBILITY"
+.SH COMPATIBILITY
As of findutils-4.2.2, shell metacharacters (`*', `?' or `[]' for
example) used in filename patterns match a leading `.', because
IEEE POSIX interpretation 126 requires this.
@@ -2679,6 +2690,7 @@ will not exit immediately. Previously,
.BR find 's
exit status was unaffected by the failure of
.BR \-delete .
+
.TS
l l l .
Feature Added in Also occurs in
@@ -2690,7 +2702,7 @@ Feature Added in Also occurs in
\-writable 4.3.0
\-executable 4.3.0
\-regextype 4.2.24
-\-exec ... + 4.2.12 POSIX
+\-exec ...\& + 4.2.12 POSIX
\-execdir 4.2.12 BSD
\-okdir 4.2.12
\-samefile 4.2.11
@@ -2712,23 +2724,23 @@ Feature Added in Also occurs in
.TE
.P
The syntax
-\.B \-perm +MODE
+.B \-perm +MODE
was removed in findutils-4.5.12, in favour of
-\.B \-perm
+.B \-perm
.BR /MODE .
The
.B +MODE
syntax had been deprecated since findutils-4.2.21
which was released in 2005.
.
-.SH "NON-BUGS"
+.SH NON-BUGS
.SS Operator precedence surprises
The command
-.B find . \-name afile \-o \-name bfile \-print
+.B find .\& \-name afile \-o \-name bfile \-print
will never print
.I afile
because this is actually equivalent to
-.BR "find . \-name afile \-o \e( \-name bfile \-a \-print \e)" .
+.BR "find .\& \-name afile \-o \e( \-name bfile \-a \-print \e)" .
Remember that the precedence of
.B \-a
is higher than that of
@@ -2738,9 +2750,9 @@ and when there is no operator specified
is assumed.
.SS \(lqpaths must precede expression\(rq error message
.nf
-.B $ find . \-name *.c \-print
+.B $ find .\& \-name *.c \-print
find: paths must precede expression
-find: possible unquoted pattern after predicate `-name'?
+find: possible unquoted pattern after predicate `\-name'?
.fi
.P
This happens when the shell could expand the pattern
@@ -2751,7 +2763,7 @@ and passing the resulting file names in
like this:
.nf
.
-.B find . \-name frcode.c locate.c word_io.c \-print
+.B find .\& \-name frcode.c locate.c word_io.c \-print
.
.fi
That command is of course not going to work, because the
@@ -2763,11 +2775,11 @@ allowing
to use the pattern with the wildcard during the search for file name matching
instead of file names expanded by the parent shell:
.nf
-.B $ find . \-name \(aq*.c\(aq \-print
-.B $ find . \-name \e*.c \-print
+.B $ find .\& \-name \(aq*.c\(aq \-print
+.B $ find .\& \-name \e*.c \-print
.fi
.
-.SH "BUGS"
+.SH BUGS
There are security problems inherent in the behaviour that the POSIX
standard specifies for
.BR find ,
@@ -2785,7 +2797,7 @@ has no effect on the
.B \-ok
action.
.
-.SH "REPORTING BUGS"
+.SH REPORTING BUGS
GNU findutils online help: <https://www.gnu.org/software/findutils/#get-help>
.br
Report any translation bugs to <https://translationproject.org/team/>
@@ -2808,7 +2820,7 @@ License GPLv3+: GNU GPL version 3 or lat
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR chmod (1),
.BR locate (1),
.BR ls (1),
@@ -2819,7 +2831,7 @@ There is NO WARRANTY, to the extent perm
.BR ctime (3)
.BR fnmatch (3),
.BR printf (3),
-.BR strftime (3),
+.BR \%strftime (3),
.BR locatedb (5),
.BR regex (7)
.PP
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option \"-warnings=w\"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT=\"-ww -b -z\"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
