find: Add -readable, -writable & -executable options

Reviewed by: jhb, Mina Galić
Pull Request: https://github.com/freebsd/freebsd-src/pull/1080

find: Allow '/' to be used with -perm for GNU compatibility

In 2005, Gnu find deprecated '+' as the leading character for the -perm
argument, instead preferring '/' with the same meaning. Implement that
behavior here, and document it in the man page.

Reviewed by: imp, emaste
Pull Request: https://github.com/freebsd/freebsd-src/pull/1060

find: Add a warning about -delete.

MFC after: 1 week
Sponsored by: Klara, Inc.
Reviewed by: pauamma_gundo.com
Differential Revision: https://reviews.freebsd.org/D43162

usr.bin: Remove ancient SCCS tags.

Remove ancient SCCS tags from the tree, automated scripting, with two
minor fixup to keep things compiling. All the common forms in the tree
were removed with a perl script.

Sponsored by: Netflix

Remove $FreeBSD$: one-line nroff pattern

Remove /^\.\\"\s*\$FreeBSD\$$\n/

find: Logic nit in man page.

Arguments follow primaries, not the other way around.

MFC after: 1 week
Sponsored by: Klara, Inc.

Reviewed by: markj
Differential Revision: https://reviews.freebsd.org/D38173

find.1: Correct the markup

- ASCII is an acronym and there is no ascii(8) manual page
- Reference ascii(7) in the SEE ALSO section

Reported by: karels
X-MFC with: 321dc6ee7e81

find.1: Fix mandoc warnings and mention a useful manpage

- new sentence, new line
- unknown AT&T UNIX version: At v7
- no blank before trailing delimiter
- reference the ASCII(8) manual page

MFC after: 5 days

find.1: small language fix after previous change

collate -> collation

find.1: explain why "find -s" may differ from "find | sort"

In short, that's because a directory name may end
with a character that goes before slash (/).

MFC after: 1 week

find(1): Update date format reference and remove cvs(1) references

cvs(1) is not installed by default. Change the date format reference to
note that find(1) understands ISO8601 and RFC822 date formats. Also
remove references to cvs(1).

PR: 254894
MFC after: 3 days
Reported by: danielsh@apache.org

find(1): Document the -f option

PR: 223127
Reported by: Mathieu Arnold <mat at FreeBSD dot org>
Reviewed by: bcr, gbe
MFC after: 3 days
Differential Revision: https://reviews.freebsd.org/D30215

ls(1): Refine the HISTORY within the manual page.

A simple find command appeared in Version 1 AT&T UNIX and was removed in
Version 3 AT&T UNIX. It was rewritten for Version 5 AT&T UNIX and later
be enhanced for the Programmer's Workbench (PWB). These changes were
later incorporated in AT&T UNIX v7.

Reviewed by: imp
MFC after: 1 week

find(1): Mark -not as an extensions to POSIX

While here, change mdoc macro from Ic to Fl.

PR: 253499
Reported by: Michael Siegel <bugcounterism at malbolge.net>

Use the Ic macro for find(1) primaries consistently

MFC after: 3 days

Renumber copyright clause 4

Renumber cluase 4 to 3, per what everybody else did when BSD granted
them permission to remove clause 3. My insistance on keeping the same
numbering for legal reasons is too pedantic, so give up on that point.

Submitted by: Jan Schaumann <jschauma@stevens.edu>
Pull Request: https://github.com/freebsd/freebsd/pull/96

Improve wording when describing -mmin.

PR: 215922
Submitted by: danielsh AT apache DOT org
Approved by: bcr (mentor)
MFC after: 5 days
Differential Revision: https://reviews.freebsd.org/D9313

find.1: Add missing whitespace:

Obtained from: Dragonfly (dee38d02d51cc8316f82b0263158d2546f2398bc)

find: Return normal exit status from -quit.

If there was an error, make the exit status reflect this even if -quit
caused the exit. Formerly, -quit always caused exit(0).

GNU find does the same.

find: Correctly propagate -exec/-execdir ... {} + exit status.

As per POSIX, the -exec ... {} + primary always returns true, but a non-zero
exit status causes find to return a non-zero exit status itself. GNU does
the same, and also for -execdir ... {} +.

It does not make much sense to return false from the primary only when the
child process happens to be run.

The behaviour for -exec/-execdir ... ; remains unchanged: the primary
returns true or false depending on the exit status, and find's exit status
is unaffected.

find: Fix two more problems with -lname and -ilname:

* Do not match symlinks that are followed because of -H or -L. This is
explicitly documented in GNU find's info file and is like -type l.

* Fix matching symlinks in subdirectories when fts changes directories.

Also, avoid some readlink() calls on files that are obviously not symlinks
(because of fts(3) restrictions, not all of them).

MFC after: 1 week

Add an option for finding sparse files.

Reviewed by: iedowse
MFC after: 3 weeks

Use .Nm instead of a self xref

Approved by: bcr (mentor)
MFC after: 1 week

Make it clear that amin and friends take + and - options.

PR: docs/173265
Submitted by: Anton Shterenlikht <mexas@bristol.ac.uk>
Approved by: bcr (mentor)
MFC after: 3 days

Note that -quit terminates successfully.

Requested by: jmg@

Document -quit, four and a half years after it was implemented.

MFC after: 3 days
Pointy hat to: imp@

find: Implement real -ignore_readdir_race.

If -ignore_readdir_race is present, [ENOENT] errors caused by deleting a
file after find has read its name from a directory are ignored.

Formerly, -ignore_readdir_race did nothing.

PR: bin/169723
Submitted by: Valery Khromov and Andrey Ignatov

find(1): Move description of -d option to -depth primary.

The nullary -depth primary is standard and the -d option provides little
advantage.

PR: docs/168885
MFC after: 1 week

Add more description and clarification about the -depth and -d options in
both places where they are mentioned in find(1).

Discussed with: dougb
PR: docs/168885
Reported by: Ronald F. Guilmette (rfg at tristatelogic dot com)
Approved by: gabor (mentor)
MFC after: 3 days

Fix style nit: don't use leading zero for dates in .Dd

Prompted by: brueffer
Approved by: brueffer
MFC after: 3 days

Document the limitations of the -delete primary

PR: bin/166554
Submitted by: Richard Kettlewell <rjk@greenend.org.uk>
Discussed with: jilles
Approved by: bcr
MFC after: 3 days

Remove trailing whitespace per mdoc lint warning

Disussed with: gavin
No objection from: doc
Approved by: joel
MFC after: 3 days

Remove superfluous paragraph macro.

Get rid of major/minor number distinction.

As of FreeBSD 6, devices can only be opened through devfs. These device
nodes don't have major and minor numbers anymore. The st_rdev field in
struct stat is simply based a copy of st_ino.

Simply display device numbers as hexadecimal, using "%#jx". This is
allowed by POSIX, since it explicitly states things like the following
(example taken from ls(1)):

"If the file is a character special or block special file, the
size of the file may be replaced with implementation-defined
information associated with the device in question."

This makes the output of these commands more compact. For example, ls(1)
now uses approximately four columns less. While there, simplify the
column length calculation from ls(1) by calling snprintf() with a NULL
buffer.

Don't be afraid; if needed one can still obtain individual major/minor
numbers using stat(1).

Move the explanation of using arguments for the PRIMARIES above
the list of PRIMARIES.

PR: 151812
Submitted by: Jay (jouellette of gmail com)
Patch by: eadler
MFC after: 1 week

Remove the advertising clause from UCB copyrighted files in usr.bin. This
is in accordance with the information provided at
ftp://ftp.cs.berkeley.edu/pub/4bsd/README.Impt.License.Change

Also add $FreeBSD$ to a few files to keep svn happy.

Discussed with: imp, rwatson

A new jail(8) with a configuration file, to replace the work currently done
by /etc/rc.d/jail.

Better way to find out available file system types is to use lsvfs(1).
Using 'sysctl vfs' is not only ugly, but is also not reliable - not all
file system types create entries in vfs sysctl tree.

Reviewed by: imp
MFC after: 1 week

Create the altix project branch. The altix project will add support
for the SGI Altix 350 to FreeBSD/ia64. The hardware used for porting
is a two-module system, consisting of a base compute module and a
CPU expansion module. SGI's NUMAFlex architecture can be an excellent
platform to test CPU affinity and NUMA-aware features in FreeBSD.

MFC r197363: Update find(1) man page for -L/-delete interaction.

It is a bit unfortunate that the example to delete broken symlinks now uses
rm(1), but allowing this with -delete would require fixing fts(3) to not
imply FTS_NOCHDIR if FTS_LOGICAL is given (or hacks in the -delete option).

PR: bin/90687

Update find(1) man page for -L/-delete interaction.

It is a bit unfortunate that the example to delete broken symlinks now uses
rm(1), but allowing this with -delete would require fixing fts(3) to not
imply FTS_NOCHDIR if FTS_LOGICAL is given (or hacks in the -delete option).

PR: bin/90687
MFC after: 2 weeks

- Import the HEAD csup code which is the basis for the cvsmode work.

Fix SYNOPSIS and usage().

Bump .Dd for revisions 1.83 and 1.84.

Tag -ilname and -lname as GNU extensions.
Correct their descriptions to indicate that it is the contents of the
symbolic link that are matched.

Implement a number of primaries present in GNU find, but not present
in our find.

The following are nops because they aren't relevant to our find:
-ignore_readdir_race
-noignore_readdir_race
-noleaf
The following aliaes were created:
-gid -> -group [2]
-uid -> -user [2]
-wholename -> -path
-iwholename -> ipath
-mount -> -xdev
-d -> -depth [1]
The following new primaries were created:
-lname like -name, but matches symbolic links only)
-ilname like -lname but case insensitive
-quit exit(0)
-samefile returns true for hard links to the specified file
-true Always true
I changed one primary to match GNU find since I think our use of it violates
POLA
-false Always false (was an alias for -not!)

Also, document the '+' modifier for -execdir, as well as all of the above.
This was previously implemented.

Document the remaining 7 primaries that are in GNU find, but aren't yet
implemented in find(1)

[1] This was done in GNU find for compatibility with FreeBSD, yet they
mixed up command line args and primary args.

[2] -uid/-gid in GNU find ONLY takes a numeric arg, but that arg does the
normal range thing that. GNU find -user and -uid also take a numberic arg,
but don't do the range processing. find(1) does both for -user and -group,
so making -uid and -gid aliases is compatible for all non-error cases used
in GNU find. While not perfect emulation, this seems a reasonable thing
for us.

Check in some insignificant fixes obtained as a result of
the translation work.

Fix the description of the -Btime primary.

Noticed by: Vadim Goncharov <vadimnuclight tpu.ru>

Update the list of POSIX extensions.

PR: docs/103859
Submitted by: shaun
MFC after: 1 week

Markup fixes.

Document that the pathname(s) following the options need not be given if
-f pathname was specified.

Add the capability for a trailing scale indicator to cause the
specified size to be read in the more familiar units of kilobytes,
megabytes, gigabytes, terabytes and petabytes.

PR: bin/50988
Submitted by: Matthew Seaman <m.seaman@infracaninophile.co.uk>
MFC after: 7 days

Note that all of the birthtime related primaries are non-standard.

Bump .Dd for the birthtime options.

Add -Btime, -Bnewer, -Bmin, -newerB[Bacmt], -newer[acmt]B options to
work with the st_birthtime field of struct stat.

'B' has been chosen to match the format specifier from stat(1).

Approved by: jhb
MFC after: 2 weeks

Markup and wording fixes.

Approved by: re (blanket)

Use rpmatch() instead of checking for responses that begin with 'y'
in queryuser(). This allows users to respond to -ok and -okdir
prompts with any affirmative reply defined by their current locale.

Scheduled mdoc(7) sweep.

Now that fnmatch() supports multibyte characters, find does too; remove
entry from BUGS section that said otherwise.

Start new sentence on new line.

Pointed out by: simon

Add a BUGS entry pointing out that -mindepth and -maxdepth are global
options even though they look like primaries. (This is already documented
in the options themselves, but is sufficiently astonishing that I think it
deserves a BUGS entry as well.)

Merge the "multibyte not supported" BUG into the pre-existing BUGS
section.

Move the HISTORY section to place it before BUGS rather than after BUGS,
in order to minimize the chance of this error being reproduced in the
future. (Both mdoc(7) and 63% of manual pages have these sections listed
in this order.)

mdoc(7) fixes.

Document missing multibyte character support in utilities specified
by POSIX.

Re-add half of UCB copyright notice that went missing in 1.20.

- introduce a new primary `-depth n', which tests whether
the depth of the current file relative to the starting
point of the traversal is n. The usual +/- modifiers
to the argument apply.

- while I'm here, fix -maxdepth in the case of a depth-first
traversal

Print the top ten maintainers of python module ports
(works with p5-* too):

find /usr/ports -depth 2 \! -name 'py-*' -prune -o \
-depth 3 -name Makefile -execdir make -VMAINTAINER \; \
| sort | uniq -c | sort -nr | head

PR: 66667
Reviewed by: ru, joerg
Approved by: joerg
MFC after: 2 weeks

Bumped document date.
Fixed a bunch of hyphen misspellings.
Fixed one warning.

snafu, exchanged the descriptions of -maxdepth and -mindepth.

Noticed by: ru

-maxdepth and -mindepth are global variables

PR: 66613
Approved by: ru
MFC after: 3 days

Clarify and correct some compatibility notes.

PR: 65822

Add -acl and a small blurb about it to the options list.
Update date.

Update the find manual page:

1: Document -follow under COMPATIBILITY.
2: Update an example to be a little more 'safe'.
3: Use '/' in place of '.' for an example; similar to other manual pages.

PR: 40196 (1), 39532 (2, 3)
Submitted by: Marc Silver <marcs@draenor.org> (2 and 3)
Discussed with: des (1)

Typo.

State that in -exec ... ; the semicolon should be quoted if invoked from
a shell.

PR: docs/54667
Submitted by: Patrick Alken <pa59@cornell.edu>
MFC after: 3 days

Uniformly refer to a file system as "file system".

Approved by: re

mdoc(7) police: markup polishing.

Approved by: re

Do not repeat the name of the flag in its description

Add a unary -not operator ala -false and !, for sake of completeness.

Obtained from: OpenDarwin
MFC after: 1 week

Oops, add -false to the operators list in the manual page for find(1), as added
in revision 1.17 of option.c.

MFC after: 1 week

Indicate that the semicolon that terminates argument lists should be in
its own argument for -ok and -okdir.

Make it more obvious that the semicolon that terminates -exec and -execdir
argument lists must be in an argument by itself, not on the end of the
previous one.

Support the SysV-style -exec utility args.. {} + function, required by
SUSv3. This is similar to find foo -print0 | xargs -0 utility args.

mdoc(7) police: markup nits.

More consistancy. file system > filesystem

Use `The .Nm utility'

find.1 does not encourage users to DTRT when piping to xargs(1)

PR: 36602
Submitted by: Joshua Goodall <joshua@roughtrade.net>
No objections from: ru
MFC after: 2 days

Run find.1 through ispell.

PR: docs/36601
Submitted by: Joshua Goodall <joshua@roughtrade.net>
MFC after: 3 days

Add a missing comma.

Document -depth

Bloat find(1) even more, and introduce the concept
of time units to be used with -[acm]time primaries.

Based on patch from Nils M Holm <nmh@t3x.org>.

PR: bin/29165, bin/30309

The implementation of -flags was broken and did not match the (poorly)
documented behavior. Only a certain set of file flags were recognized,
and "no" flags did not match files that have corresponding flags bits
turned off.

Fix and extend the -flags functionality as follows:

: -flags [-|+]<flags>,<notflags>
: The flags are specified using symbolic names (see chflags(1)).
: Those with the "no" prefix (except "nodump") are said to be
: <notflags>. Flags in <flags> are checked to be set, and flags in
: <notflags> are checked to be not set. Note that this is different
: from -perm, which only allows the user to specify mode bits that
: are set.
:
: If flags are preceded by a dash (``-''), this primary evaluates
: to true if at least all of the bits in <flags> and none of the bits
: in <notflags> are set in the file's flags bits. If flags are pre-
: ceded by a plus (``+''), this primary evaluates to true if any of
: the bits in <flags> is set in the file's flags bits, or any of the
: bits in <notflags> is not set in the file's flags bits. Otherwise,
: this primary evaluates to true if the bits in <flags> exactly match
: the file's flags bits, and none of the <flags> bits match those of
: <notflags>.

MFC after: 2 weeks

Sort predicates.

PR: docs/30237

Clarify the feature that -exec parameters won't get
shell-expanded when the specified utility is run.

MFC after: 5 days

mdoc(7) police: fix markup.

They add the following commands:
-anewer
-cnewer
-mnewer
-okdir
-newer[acm][acmt]

With it, you can form queries like

find . -newerct '1 minute ago' -print

As an extra bonus, the program is ANSI-fied - the original version
relies on some obscure features of K&R C.

(This PR was submitted in 1999, and the submittor has kept the patch
updated ever since, hats off for him guys, and how about you close a PR ??)

PR: 9374
Submitted by: Martin Birgmeier <Martin.Birgmeier@aon.at>

mdoc(7) police: restore correct order of references in the SEE ALSO.

Implement the following options and primaries:

-E Interpret regular expressions followed by -regex and -iregex op-
tions as extended (modern) regular expressions rather than basic
regular expressions (BRE's). The re_format(7) manual page fully
describes both formats.

-iname pattern
Like -name, but the match is case insensitive.

-ipath pattern
Like -path, but the match is case insensitive.

-regex pattern
True if the whole path of the file matches pattern using regular
expression. To match a file named ``./foo/xyzzy'', you can use
the regular expression ``.*/[xyz]*'' or ``.*/foo/.*'', but not
``xyzzy'' or ``/foo/''.

-iregex pattern
Like -regex, but the match is case insensitive.

These are meant to be compatible with other find(1) implementations
such as GNU's or NetBSD's except regexp library differences.

Reviewed by: sobomax, dcs, and some other people on -current

mdoc(7) police: split punctuation characters + misc fixes.

Add the -empty flag, from OpenBSD. It returns true if the directory
is empty. There doesn't appear to be another easy way to do this.

mobile# mkdir foo
mobile# mkdir foo/bar
mobile# mkdir bar
mobile# find . -empty
./foo/bar
./bar

Prepare for mdoc(7)NG.

Prepare for mdoc(7)NG.

mdoc(7) police: use the new features of the Nm macro.

"minute(s) period(s)" --> "minute(s)"

This patch adds the -mindepth and -maxdepth options to find(1), which
behave as in GNU find (and of course as described in the manual page
diff included). I think these options would be useful for some people.

Some missing $FreeBSD$ tags are also added.

The patch was slightly modified (send-pr mangling of TABS).

PR: bin/18941
Submitted by: Ben Smithurst <ben@scientia.demon.co.uk>

The find -perm option currently supports an exact match,
or if the mode is preceded by a '-', it checks for a match
in at least the bits specified on the command line. It is
often desirable to find things with any execute or setuid or
setgid bits set.

PR: bin/10169
Submitted by: Monte Mitzelfelt <monte@gonefishing.org>

Fix errors in .Xr usage.

PR: docs/17057
Submitted by: Submitted by: Udo Erdelhoff <ue@nathan.ruhr.de>

Second part of bin/3648: add -flags to search for specific flags.
I added $FreeBSD$ whicle I was here. The patch wasn't usable anymore
due to its age so I adapted it.

PR: bin/3648
Submitted by: Martin Birgmeier <mbirg@austria.ds.philips.com>

$Id$ -> $FreeBSD$

The -perm option takes argument [-]mode, not [-mode]

Obtained from: NetBSD, by way of OpenBSD

Clarify wording to indicate that the arguments to find(1) are path names
(and can be both files or directories). Show white space between
"(", ")", "!" and their corresponding `expression' arguments as
expected by the expression parser inside find(1).

Prompted by: David Honig <David.Honig@idt.com> on freebsd-doc
Message-Id: <199904132055.NAA09432@justinian.Eng.idt.com>

Typo - "the -delete primary do not.." -> "the -delete primary does not.."

PR: docs/9255
Submitted by: Christian Weisgerber <naddy@bigeye.rhein-neckar.de>

Fixed English in previous commit. Clarify "lexicographical order".
Don't format paragraphs manually (new sentences not beginning on new
lines give hard-formatted line breaks).

Added a sort option to find(1).

The sort option make it possible to build the locate
database without large (usually 20-100MB) temp files.

Add cross references for find(1), locate(1), whereis(1) and which(1).

Submitted by: Josh Gillam <josh@quick.net>
PR: docs/6642

Better wording explaining that all single character options
are extensions along with the previous list of primaries.

Suggested by: bde

Offending statement removed from STANDARDS section. From what I
can gather from the Posix spec that I have (which is very old)
all one character options are extensions to Posix.

PR: docs/4701

Add the primaries -mmin, -amin, -cmin to find, similar to the GNU find.

Add -execdir which will execute the exec command in the dir of the file
in question. This change and the fts changes should be merged into 2.2-stable
as soon as they are vetted in -current. This should allow cleaning of files
in /tmp to be reneabled.
Obtained from: OpenBSD

Mention that "-P" is the default.

`it's'' -> `its'' where appropriate and typo fixes in time2posix.3.

Closes PR docs/3612.

Submitted by: Josh Gilliam <soil@quick.net>

Minor typo.
PR: 3472
Submitted by: Josh Gilliam <soil@quick.net>

Merge from Lite2 - use new getvfsbyname() and related changes.
understand whiteouts (FTS_W from fts()).

Import some parts of CSRG 4.4BSD-Lite2 usr.bin sources to fix tree build.

Revert $FreeBSD$ to $Id$

Make the long-awaited change from $Id$ to $FreeBSD$

This will make a number of things easier in the future, as well as (finally!)
avoiding the Id-smashing problem which has plagued developers for so long.

Boy, I'm glad we're not using sup anymore. This update would have been
insane otherwise.

Implement a -delete option to find. The code is extremely paranoid and
goes to a fair degree of trouble to enable something like this to
be safe: cd /tmp && find . -mtime +7 -delete

It removes both files and directories. It does not attempt to remove
immutable files (an earlier version I showed to a few people did a chflags
and tried to blow away even immutable files. Too risky..)

It is thought to be safe because it forces the fts(3) driven descent to
only do "minimal risk" stuff. specifically, -follow is disabled, it does
checking to see that it chdir'ed to the directory it thought it was
going to, it will *not* pass a pathname with a '/' character in it to
unlink(), so it should be totally immune to symlink tree races. If it runs
into something "fishy", it bails out rather than blunder ahead.. It's better
to do that if somebody is trying to compromise security rather than risk
giving them an opportunity. Since the unlink()/rmdir() is being called
from within the current working directory during the tree descent, there
are no fork/exec overheads or races.

As a side effect of this paranoia, you cannot do a
"find /somewhere/dir -delete", as the last argument to rmdir() is
"/somewhere/dir", and the checking won't allow it. Besides, one would use
rm -rf for that case anyway. :-)

Reviewed by: pst (some time ago, but I've removed the immutable file
deletion code that he complained about since he last saw it)

[HISTORY] command appeared in Version 1 AT&T UNIX
Obtained from: A Quarter Century of UNIX, Peter H. Salus, page 41

Add GNU-style `-print0' primary. This exists so that one can safely
do `find some-nasty-expression -print0 | perl -n0e unlink' and have all
the files actuallly get deleted. (Using `xargs' and `rm' is not safe.)

BSD 4.4 Lite Usr.bin Sources