From 010a755370eeb7450c0def58a8d5830ddcca7938 Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Wed, 6 Feb 2019 23:22:26 -0500 Subject: Re-write the help/manpage I'm not sure people care very much whether the functionality they're looking up originated in POSIX/BSD/GNU find (and if they do, they can check those docs). --- bfs.1 | 616 ++++++++++++++++++++++++++++++------------------------------------ 1 file changed, 277 insertions(+), 339 deletions(-) (limited to 'bfs.1') diff --git a/bfs.1 b/bfs.1 index 9c7f14c..e33513e 100644 --- a/bfs.1 +++ b/bfs.1 @@ -80,8 +80,69 @@ and .I +N means "greater than .IR N ." -.SH POSIX find FEATURES -Operators: +.SH FLAGS +.TP +.B \-H +Follow symbolic links on the command line, but not while searching. +.TP +.B \-L +Follow all symbolic links. +.TP +.B \-P +Never follow symbolic links (the default). +.TP +.B \-E +Use extended regular expressions (same as \fB\-regextype posix-extended\fR). +.TP +.B \-X +Filter out files with +.RB non- xargs (1)-safe +names. +.TP +.B \-d +Search in post-order (same as +.BR \-depth ). +.TP +.B \-x +Don't descend into other mount points (same as \fB\-xdev\fR). +.TP +\fB\-f \fIPATH\fR +Treat +.I PATH +as a path to search (useful if it begins with a dash). +.PP +.TP +\fB\-D \fIFLAG\fR +Turn on a debugging flag (see +.B \-D +.IR help ). +.PP +\fB\-O\fIN\fR +.RS +Enable optimization level +.I N +(default: 3) +.TP +\fB\-O\fI0\fR +Disable all optimizations. +.TP +\fB\-O\fI1\fR +Basic logical simplifications. +.TP +\fB\-O\fI2\fR +All +.BI \-O 1 +optimizations, plus dead code elimination and data flow analysis. +.TP +\fB\-O\fI3\fR +All +.BI \-O 2 +optimizations, plus re-order expressions to reduce expected cost. +.TP +\fB\-O\fI4\fR/\fB\-O\fIfast\fR +All optimizations, including aggressive optimizations that may alter the observed behavior in corner cases. +.RE +.SH OPERATORS .TP \fB( \fIexpression \fB)\fR Parentheses are used for grouping expressions together. @@ -90,13 +151,22 @@ You'll probably have to write .I expression .B \\\\) to avoid the parentheses being interpreted by the shell. -.TP +.PP \fB! \fIexpression\fR +.br +\fB\-not \fIexpression\fR +.RS The "not" operator: returns the negation of the truth value of the .IR expression . You may have to write \fB\\! \fIexpression\fR to avoid \fB!\fR being interpreted by the shell. -.TP -\fIexpression\fR [\fB\-a\fR] \fIexpression\fR +.RE +.PP +\fIexpression\fR \fIexpression\fR +.br +\fIexpression \fB\-a \fIexpression\fR +.br +\fIexpression \fB\-and \fIexpression\fR +.RS Short-circuiting "and" operator: if the left-hand .I expression is @@ -105,8 +175,12 @@ returns the right-hand .IR expression ; otherwise, returns .BR false . -.TP +.RE +.PP \fIexpression \fB\-o \fIexpression\fR +.br +\fIexpression \fB\-or \fIexpression\fR +.RS Short-circuiting "or" operator: if the left-hand .I expression is @@ -115,160 +189,39 @@ returns the right-hand .IR expression ; otherwise, returns .BR true . -.LP -Flags: -.TP -.B \-H -Follow symbolic links on the command line, but not while searching. -.TP -.B \-L -Follow all symbolic links. -.LP -Options: -.TP -.B \-depth -Search in post-order (descendents first). -.TP -.B \-xdev -Don't descend into other mount points. -.LP -Tests: -.PP -\fB\-atime\fR [\fI\-+\fR]\fIN\fR -.br -\fB\-ctime\fR [\fI\-+\fR]\fIN\fR -.br -\fB\-mtime\fR [\fI\-+\fR]\fIN\fR -.RS -Find files -.BR a ccessed/ c hanged/ m odified -.I N -days ago. -.RE -.PP -.B \-group NAME -.br -.B \-user NAME -.RS -Find files owned by the group/user -.BR NAME . .RE .TP -\fB\-links\fR [\fI\-+\fR]\fIN\fR -Find files with -.I N -hard links. -.TP -\fB\-name \fIGLOB\fR -Find files whose name matches the -.IR GLOB . -.TP -\fB\-path \fIGLOB\fR -Find files whose entire path matches the -.IR GLOB . -.TP -\fB\-newer \fIFILE\fR -Find files newer than -.IR FILE . -.TP -\fB\-perm\fR [\fI\-\fR]\fIMODE\fR -Find files with a matching mode. -.TP -\fB\-type\fR [\fIbcdlpfs\fR] -Find files of the given type. -Possible types are -.IR b lock -device, -.IR c haracter -device, -.IR d irectory, -symbolic -.IR l ink, -.IR p ipe, -regular -.IR f ile, -and -.IR s ocket. -.TP -\fB\-size\fR [\fI\-+\fR]\fIN\fR[\fIc\fR] -Find files with the given size. -The default unit is 512-byte blocks; -.I c -counts -.IR c haracters/bytes -instead. -.LP -Actions: -.TP -.B \-prune -Don't descend into this directory. -.TP -\fB\-exec \fIcommand ... {} ;\fR -Execute a command. -.TP -\fB\-exec \fIcommand ... {} +\fR -Execute a command with multiple files at once. -.TP -\fB\-ok \fIcommand ... {} ;\fR -Prompt the user whether to execute a command. -.TP -.B \-print -Print the path to the found file. -.SH GNU find FEATURES -Operators: -.TP -\fB\-not \fIexpression\fR -Same as \fB! \fIexpression\fR. -.TP -\fIexpression \fB\-and \fIexpression\fR -Same as -.I expression -.B \-a -.IR expression . -.TP -\fIexpression \fB\-or \fIexpression\fR -Same as -.I expression -.B \-o -.IR expression . -.TP \fIexpression \fB, \fIexpression\fR The "comma" operator: evaluates the left-hand .I expression but discards the result, returning the right-hand .IR expression . -.LP -Flags: -.TP -.B \-P -Never follow symbolic links (the default). -.TP -\fB\-D \fIFLAG\fR -Turn on a debugging flag (see -.B \-D -.IR help ). -.TP -\fB\-O\fIN\fR -Enable optimization level -.I N -(default: 3; interpreted differently than GNU find -- see below). -.LP -Options: -.TP -.B \-d -Search in post-order (same as -.BR \-depth ). +.SH OPTIONS +.PP +.B \-color +.br +.B \-nocolor +.RS +Turn colors on or off (default: +.B \-color +if outputting to a terminal, +.B \-nocolor +otherwise). +.RE .TP .B \-daystart Measure time relative to the start of today. .TP +.B \-depth +Search in post-order (descendents first). +.TP .B \-follow Follow all symbolic links (same as .BR \-L ). -.LP -.B \-ignore_readdir_race +.PP +\fB\-ignore_readdir_race\fR .br -.B \-noignore_readdir_race +\fB\-noignore_readdir_race\fR .RS Whether to report an error if .B bfs @@ -283,10 +236,13 @@ detects that the file tree is modified during the search (default: Ignore files deeper/shallower than .IR N . .RE -.TP +.PP .B \-mount -Don't descend into other mount points (same as -.BR \-xdev ). +.br +.B \-xdev +.RS +Don't descend into other mount points. +.RE .TP .B \-noleaf Ignored; for compatibility with GNU find. @@ -299,44 +255,75 @@ regexes (default: see .B \-regextype .IR help ). -.LP +.PP .B \-warn .br .B \-nowarn .RS Turn on or off warnings about the command line. .RE -.PP -Tests: +.SH TESTS +.TP +.B \-acl +Find files with non-trivial +.BR acl (5) +(Access Control Lists). .PP \fB\-amin\fR [\fI\-+\fR]\fIN\fR .br +\fB\-Bmin\fR [\fI\-+\fR]\fIN\fR +.br \fB\-cmin\fR [\fI\-+\fR]\fIN\fR .br \fB\-mmin\fR [\fI\-+\fR]\fIN\fR .RS Find files -.BR a ccessed/ c hanged/ m odified +.BR a ccessed/ B irthed/ c hanged/ m odified .I N minutes ago. .RE .PP \fB\-anewer \fIFILE\fR .br +\fB\-Bnewer \fIFILE\fR +.br \fB\-cnewer \fIFILE\fR .br \fB\-mnewer \fIFILE\fR .RS Find files -.BR a ccessed/ c hanged/ m odified +.BR a ccessed/ B irthed/ c hanged/ m odified more recently than .I FILE was modified. .RE +.PP +\fB\-atime\fR [\fI\-+\fR]\fIN\fR +.br +\fB\-Btime\fR [\fI\-+\fR]\fIN\fR +.br +\fB\-ctime\fR [\fI\-+\fR]\fIN\fR +.br +\fB\-mtime\fR [\fI\-+\fR]\fIN\fR +.RS +Find files +.BR a ccessed/ B irthed/ c hanged/ m odified +.I N +days ago. +.RE +.TP +.B \-capable +Match files with POSIX.1e +.BR capabilities (7) +set. +.TP +\fB\-depth\fR [\fI\-+\fR]\fIN\fR +Find files with depth +.IR N . .TP .B \-empty Find empty files/directories. -.LP +.PP .B \-executable .br .B \-readable @@ -356,7 +343,7 @@ Always false/true. .B \-fstype TYPE Find files on file systems with the given .BR TYPE . -.LP +.PP \fB\-gid\fR [\fI\-+\fR]\fIN\fR .br \fB\-uid\fR [\fI\-+\fR]\fIN\fR @@ -364,15 +351,54 @@ Find files on file systems with the given Find files owned by group/user ID .IR N . .RE +.PP +\fB\-group \fINAME\fR +.br +\fB\-user \fINAME\fR +.RS +Find files owned by the group/user +.IR NAME . +.RE +.TP +.B \-hidden +Match hidden files (those beginning with +.IR . ). +.PP +\fB\-ilname \fIGLOB\fR +.br +\fB\-iname \fIGLOB\fR +.br +\fB\-ipath \fIGLOB\fR +.br +\fB\-iregex \fIREGEX\fR +.br +\fB\-iwholename \fIGLOB\fR +.RS +Case-insensitive versions of +.BR \-lname / \-name / \-path / \-regex / \-wholename . +.RE .TP \fB\-inum\fR [\fI\-+\fR]\fIN\fR Find files with inode number .IR N . .TP +\fB\-links\fR [\fI\-+\fR]\fIN\fR +Find files with +.I N +hard links. +.TP \fB\-lname \fIGLOB\fR Find symbolic links whose target matches the .IR GLOB . .TP +\fB\-name \fIGLOB\fR +Find files whose name matches the +.IR GLOB . +.TP +\fB\-newer \fIFILE\fR +Find files newer than +.IR FILE . +.TP \fB\-newer\fIXY \fIREFERENCE\fR Find files whose .I X @@ -386,6 +412,24 @@ and can be any of .RI [ aBcm ] .RI ( a ccess/ B irth/ c hange/ m odification). +.PP +.B \-nogroup +.br +.B \-nouser +.RS +Find files owned by nonexistent groups/users. +.RE +.PP +\fB\-path \fIGLOB\fR +.br +\fB\-wholename \fIGLOB\fR +.RS +Find files whose entire path matches the +.IR GLOB . +.RE +.TP +\fB\-perm\fR [\fI\-\fR]\fIMODE\fR +Find files with a matching mode. .TP \fB\-regex \fIREGEX\fR Find files whose entire path matches the regular expression @@ -395,56 +439,64 @@ Find files whose entire path matches the regular expression Find hard links to .IR FILE . .TP -\fB\-size\fR [\fI\-+\fR]\fIN\fR[\fIcwbkMG\fR] -1-byte +\fB\-size\fR [\fI\-+\fR]\fIN\fR[\fIcwbkMGTP\fR] +Find files with the given size, in 1-byte .IR c haracters, 2-byte .IR w ords, 512-byte .IR b locks, -and -.IR k iB/ M iB/ G iB. +(default) or +.IR k iB/ M iB/ G iB/ T iB/ P iB. .TP -\fB\-type\fR [\fIbcdlpfsD\fR] -The -.IR D oor -file type is also supported on platforms that have it (Solaris). +.B \-sparse +Find files that occupy fewer disk blocks than expected. +.TP +\fB\-type\fR [\fIbcdlpfswD\fR] +Find files of the given type. +Possible types are +.IR b lock +device, +.IR c haracter +device, +.IR d irectory, +symbolic +.IR l ink, +.IR p ipe, +regular +.IR f ile, +.IR s ocket, +.IR w hiteout, +and +.IR D oor. .TP \fB\-used\fR [\fI\-+\fR]\fIN\fR Find files last accessed .I N days after they were changed. .TP -\fB\-wholename \fIGLOB\fR -Find files whose entire path matches the -.I GLOB -(same as -.BR \-path ). -.LP -\fB\-ilname \fIGLOB\fR -.br -\fB\-iname \fIGLOB\fR -.br -\fB\-ipath \fIGLOB\fR -.br -\fB\-iregex \fIREGEX\fR -.br -\fB\-iwholename \fIGLOB\fR -.RS -Case-insensitive versions of -.BR \-lname / \-name / \-path / \-regex / \-wholename . -.RE -.TP -\fB\-xtype\fR [\fIbcdlpfsD\fR] +\fB\-xtype\fR [\fIbcdlpfswD\fR] Find files of the given type, following links when .B \-type would not, and vice versa. -.LP -Actions: -.TP +.SH ACTIONS +.PP .B \-delete +.br +.B \-rm +.RS Delete any found files (implies \fB-depth\fR). -.LP +.RE +.TP +\fB\-exec \fIcommand ... {} ;\fR +Execute a command. +.TP +\fB\-exec \fIcommand ... {} +\fR +Execute a command with multiple files at once. +.TP +\fB\-ok \fIcommand ... {} ;\fR +Prompt the user whether to execute a command. +.PP \fB\-execdir \fIcommand ... {} ;\fR .br \fB\-execdir \fIcommand ... {} +\fR @@ -456,23 +508,9 @@ Like but run the command in the same directory as the found file(s). .RE .TP -.B \-ls -List files like -.B ls -.IR \-dils . -.TP -.B \-print0 -Like -.BR \-print , -but use the null character ('\\0') as a separator rather than newlines. -Useful in conjunction with -.B xargs -.IR -0 . -.TP -\fB\-printf \fIFORMAT\fR -Print according to a format string (see -.BR find (1)). -.LP +\fB\-exit\fR [\fISTATUS\fR] +Exit immediately with the given status (0 if unspecified). +.PP \fB\-fls \fIFILE\fR .br \fB\-fprint \fIFILE\fR @@ -488,81 +526,41 @@ but write to instead of standard output. .RE .TP -.B \-quit -Quit immediately. -.TP -.B \-version -Print version information. -.TP -.B \-help -Print usage information. -.SH BSD find FEATURES -Flags: -.TP -.B \-E -Use extended regular expressions (same as \fB\-regextype posix-extended\fR). +.B \-ls +List files like +.B ls +.IR \-dils . .TP -.B \-X -Filter out files with -.RB non- xargs (1)-safe -names. +.B \-nohidden +Filter out hidden files and directories. .TP -.B \-x -Don't descend into other mount points (same as \fB\-xdev\fR). +.B \-print +Print the path to the found file. .TP -\fB\-f \fIPATH\fR -Treat -.I PATH -as a path to search (useful if it begins with a dash). -.LP -Tests: +.B \-print0 +Like +.BR \-print , +but use the null character ('\\0') as a separator rather than newlines. +Useful in conjunction with +.B xargs +.IR -0 . .TP -.B \-acl -Find files with non-trivial -.BR acl (5) -(Access Control Lists). -.PP -\fB\-Bmin\fR [\fI\-+\fR]\fIN\fR -.br -\fB\-Btime\fR [\fI\-+\fR]\fIN\fR +\fB\-printf \fIFORMAT\fR +Print according to a format string (see +.BR find (1)). +These additional format directives are supported: .RS -Find files -.BR B irthed -.I N -minutes/days ago. -.RE .TP -\fB\-Bnewer \fIFILE\fR -Find files -.BR B irthed -more recently than -.I FILE -was modified. +%w +The file's birth time, in the same format as %a/%c/%t. .TP -\fB\-depth\fR [\fI\-+\fR]\fIN\fR -Find files with depth -.IR N . -.LP -.B \-gid NAME -.br -.B \-uid NAME -.RS -Group/user names are supported in addition to numeric IDs. +.RI %W k +Field +.I k +of the file's birth time, in the same format as +.RI %A k /%C k /%T k . .RE .TP -\fB\-size\fR [\fI\-+\fR]\fIN\fR[\fIcwbkMGTP\fR] -Units of -.IR T iB/ P iB -are additionally supported. -.TP -.B \-sparse -Find files that occupy fewer disk blocks than expected. -.LP -Actions: -.TP -\fB\-exit\fR [\fISTATUS\fR] -Exit immediately with the given status (0 if unspecified). -.TP .B \-printx Like .BR \-print , @@ -575,77 +573,17 @@ and .I \-0 instead. .TP -.B \-rm -Delete any found files (same as -.BR \-delete ; -implies -.BR \-depth ). -.SH bfs-SPECIFIC FEATURES -Flags: -.TP -\fB\-O\fI0\fR -Disable all optimizations. -.TP -\fB\-O\fI1\fR -Basic logical simplifications. -.TP -\fB\-O\fI2\fR -All -.BI \-O 1 -optimizations, plus dead code elimination and data flow analysis. -.TP -\fB\-O\fI3\fR -All -.BI \-O 2 -optimizations, plus re-order expressions to reduce expected cost. -.TP -\fB\-O\fI4\fR/\fB\-O\fIfast\fR -All optimizations, including aggressive optimizations that may alter the observed behavior in corner cases. -.LP -Options: -.PP -.B \-color -.br -.B \-nocolor -.RS -Turn colors on or off (default: -.B \-color -if outputting to a terminal, -.B \-nocolor -otherwise). -.RE -.PP -Tests: -.TP -.B \-capable -Match files with POSIX.1e -.BR capabilities (7) -set. -.TP -.B \-hidden -Match hidden files (those beginning with -.IR . ). -.LP -Actions: +.B \-prune +Don't descend into this directory. .TP -.B \-nohidden -Filter out hidden files and directories. -.LP -\fB\-printf \fIFORMAT\fR -.br -\fB\-fprintf \fIFORMAT FILE\fR -.RS -These additional format directives are supported: +.B \-quit +Quit immediately. .TP -%w -The file's birth time, in the same format as %a/%c/%t. +.B \-version +Print version information. .TP -.RI %W k -Field -.I k -of the file's birth time, in the same format as -.RI %A k /%C k /%T k . -.RE +.B \-help +Print usage information. .SH EXAMPLES .TP .B bfs -- cgit v1.2.3