.\" This file is in the public domain.
.Dd September 25, 2011
.Dt MFIND 1
.Os NetBSD 1.4T
.Sh NAME
.Nm mfind
.Nd Mouse's find
.Sh SYNOPSIS
.Nm
.Ar dir ...
.Ar expression
.Sh DESCRIPTION
.Nm
walks directory trees looking for objects matching the
.Ar expression .
.Pp
The
.Ar dir Ns No s
consist of all arguments up until the first argument that could begin
an expression, usually the first argument beginning with a \-; the
.Ar expression
begins at that point and continues to the end of the arglist.
.Pp
.Nm
walks the tree under each
.Ar dir ,
evaluating the
.Ar expression
for each object found.  Nothing in particular is done with the result
of evaluating the expression; it is primitives with side effects (such
as
.Fl print )
that make
.Nm
useful.  The
.Ar expression
is built up from
.Sq primitives ,
such as
.Fl newer ,
in the usual way.  \&(\ ) are used for grouping and \&! for negation;
.Sq and
is indicated by simple juxtaposition, or
.Fl a
if necessary, and
.Sq or
is indicated by
.Fl o .
Each of these \- parentheses, \&!, etc \- must be a separate argument
to
.Nm mfind .
Each primitive must also be one argument, or more in the case of
primitives (such as
.Fl newer )
that take arguments.  Some arguments will typically need quoting to
protect them from the shell.
.Pp
The available primitives, and their semantics, are as follows.  An
object's
.Sq name
is its name within its containing directory, that is, just the last
component of its path; its
.Sq path
is the full path, including the
.Ar dir
it was found under and all intermediate directories and slashes.  When
an argument is called a
.Sq comparator
or
.Sq time comparator ,
exactly how it works is more complicated; see the
.Sq COMPARATORS
section below for details.
.Bl -tag -width indent
.It Fl name Ar pattern
True if the object's name maches
.Ar pattern .
See the
.Sq PATTERNS
section for more.
.It Fl qname Ar string
True if the object's name exactly equals
.Ar string .
.It Fl path Ar pattern
True if the object's path maches
.Ar pattern .
See the
.Sq PATTERNS
section for more.
.It Fl qpath Ar string
True if the object's path exactly equals
.Ar string .
.It Fl linkto Ar pattern
True if the object is a symbolic link whose link-to string matches
.Ar pattern .
See the
.Sq PATTERNS
section for more.
.It Fl qlinkto Ar string
True if the object is a symbolic link whose link-to string exactly
equals
.Ar string .
.It Fl perm Ar arg
Tests the object's permission bits.  If
.Ar arg
is a permission spec (see below), the test returns true exactly when
the object's permission bits, ANDed with 0777, equal
.Ar arg .
If
.Ar arg
is a permission spec with a dash before it, the same test is applied,
except that the mask is 017777.
If
.Ar arg
is two permission specs with a slash between them,
.Ar n1 Ns No / Ns Ar n2 ,
then the test ANDs the object's permission bits with
.Ar n1
and then returns true exactly when the result equals
.Ar n2 .
.Pp
A
.Sq permission spec
can be an octal number, or it can be a nine-character
.Xr ls 1 Ns No -style
mode matching the pattern
.Dl [-r][-w][-xsS][-r][-w][-xsS][-r][-w][-xtT]
or it can be a ten-character
.Xr ls 1 Ns No -style
mode matching the pattern
.Dl [-bcdflps][-r][-w][-xsS][-r][-w][-xsS][-r][-w][-xtT]
Nine-character
.Xr ls 1 Ns No -style
modes evaluate to 12-bit values and thus are suitable for testing just
the permission bits; ten-character modes include the
.Dv S_IFMT
values as well and thus can test object type as well as permissions in
a single operation.
.It Fl prune
This always returns true.  However, in doing so, it has a side effect.
Specifically, it arranges that, if the current object is a directory,
.Nm
will not descend into that directory.
.It Fl type Ar T
This tests the object's type.  It returns true when the object's type
is included in
.Ar T ,
where
.Ar T
can contain zero or more of
.Ar b ,
.Ar c ,
.Ar d ,
.Ar f ,
.Ar p ,
.Ar l ,
or
.Ar s ,
to match, respectively,
.Sq block special device ,
.Sq character special devices ,
.Sq directory ,
.Sq plain file ,
.Sq FIFO ,
.Sq symbolic link ,
or
.Sq socket .
.It Fl links Ar cmp
.Ar cmp
is a comparator applying to the object's link count.
.It Fl user Ar uid
Returns true when the user ID owning the object equals
.Ar uid Ap s ;
.Ar uid
can be a name (which is looked up with
.Xr getpwnam 3
in the usual way) or a number.
.It Fl nouser
Returns true when the user ID owning the object does not match any
user's ID (see
.Xr getpwuid 3 ) .
.It Fl group Ar gid
Returns true when the group ID owning the object equals
.Ar gid Ap s ;
.Ar gid
can be a name (which is looked up with
.Xr getgrnam 3
in the usual way) or a number.
.It Fl nogroup
Returns true when the group ID owning the object does not match any
group's ID (see
.Xr getgrgid 3 ) .
.It Fl size Ar cmp
If
.Ar cmp
is an ordinary comparator, it is multiplied by 512; if it has a
.Sq c
appended, it is not multipled.  Either way, the resulting number is a
comparator applying to the object's size in bytes.
.It Fl inum Ar cmp
.Ar cmp
is a comparator applying to the object's inumber.
.It Fl atime Ar tcmp
.Ar tcmp
is a time comparator applying to the object's atime.
.It Fl mtime Ar tcmp
.Ar tcmp
is a time comparator applying to the object's mtime.
.It Fl ctime Ar tcmp
.Ar tcmp
is a time comparator applying to the object's ctime.
.It Fl exec Ar command arg ... No \&;
Runs the given
.Ar command
with the given
.Ar arg Ns No s .
If it terminates successfully (exits with code 0, see
.Xr wait 2 ) ,
then the
.Fl exec
evaluates true, otherwise, false.  Any of the
.Ar arg Ns No s
which are the two-character string
.Sq \&{}
are replaced with the current object's path.  The terminating semicolon
in particular will usually have to be quoted to protect it from the
shell.
.Pp
Note that the command is run with
.Xr execvp 3 ,
not by running a shell.
.It Fl ok Ar command arg ... No \&;
This is just like
.Fl exec
except that the command is not necessarily run.  Instead, the proposed
command is printed to
.Nm mfind Ap s
standard output and a line is read from its standard input.  If the
line begins with
.Sq y ,
then the command is run and the result of the evaluation determined as
described for
.Fl exec ;
otherwise, the command is not run and the
.Fl ok
primitive evaluates true.
.It Fl print
Always evaluates true.  As a side effect, the current object's path is
printed to standard output, followed by a newline.
.It Fl print0
Always evaluates true.  As a side effect, the current object's path is
printed to standard output, followed by a NUL.
.It Fl printn
Always evaluates true.  As a side effect, the current object's path is
printed to standard output, prefixed by its length in ASCII decimal and
exactly one space and suffixed by a newline.
.It Fl count
Always evaluates true.  As a side effect, a count of the number of
times it is evaluated is kept; this count is printed just
before
.Nm
exits.  (If multiple
.Ar dir Ns No s
are given on the command line, only one count is printed, the total
over all of them.)  This count is printed if
.Fl count
appears in the expression, even if it is never evaluated at all.  Note
that if
.Fl count
appears more than once in the expression, the count may be incremented
more than once for some objects.
.It Fl tcount Ar TAG
This is just like
.Fl count
except that multiple counts are (potentially) accumulated.  Each
.Ar TAG
string corresponds to a separate count; when counts are printed at the
end of the run, each count is printed with the correspnoding
.Ar TAG .
.Pp
If multiple count lines are printed (if
.Fl tcount Ns No s
with multiple distinct
.Ar TAG Ns No s
are given, or if both
.Fl tcount
and
.Fl count
are used), the order in which they are printed is specifically not
defined.
.It Fl ls
Always evaluates true.  This is just like
.Fl lsf Ar '6i\ 4b\ p\ 2l\ -8u\ -8g\ 8s\ m\ n' .
.It Fl lsf Ar format
Always evaluates true.  This prints information about the current
object as selected by
.Ar format .
.Ar format
can contain whitespace, which is simply copied to the output string,
quoted characters (quoting with \&", \&', and \e works in the usual
ways), which are also simply copied to the output, and (potentially
number-prefixed) format characters, which print information about the
current object.  Other characters, if they appear, are ignored.  The
format characters, with their semantics, are:
.Bl -tag -width indent
.It b
Prints the number of blocks
.Pf ( Dv st_blocks ,
see
.Xr stat 2 ) .
.It i
Prints the inumber
.Pf ( Dv st_ino ,
see
.Xr stat 2 ) .
.It l
Prints the link count
.Pf ( Dv st_nlink ,
see
.Xr stat 2 ) .
.It s
Prints the size
.Pf ( Dv st_size ,
see
.Xr stat 2 ) .
.It g
Prints the owning group (name if it has one, number otherwise).
.It m
Prints the mtime.
.It N
Prints the full pathname.
.It p
Prints the mode, ls-style.
.It u
Prints the owning user (name if it has one, number otherwise).
.It n
If the object is a symbolic link, prints its path, an arrow, and its
link-to string; otherwise, just prints its path.
.It L
If the object is a symbolic link, prints its link-to string; otherwise,
prints a single question mark.
.El
.Pp
If a number is given before the format character, it is a field width,
somewhat a la
.Xr printf 3 ;
numbers may also be prefixed with a \-, in which case the value is
left-justified in the field (the default is right-justified).
.It Fl newer Ar file
Returns true when the object's mtime is newer than
.Ar file Ap s .
(More precisely, the comparison is not against
.Ar file Ap s
mtime at the time the comparison is done, but rather against its mtime
at the time the
.Ar expression
was parsed.)
.It Fl depth
This always evaluates true.  However, its appearance in the
.Ar expression
(regardless of whether it ever gets evaluated) causes
.Nm
to do a depth-first traversal, meaning that a directory's contents are
processed before the directory itself is.  (By default, a directory is
processed before its contents.  Note also that
.Fl depth Ns No -style
processing makes
.Fl prune
useless, because by the time the
.Ar expression
is evaluated for a directory, it's too late to prevent
.Nm
from descending into it.)
.El
There are also four more primitives which are recognized but not
implemented:
.Pp
.Bl -item -compact
.It
.Fl fstype Ar type
.It
.Fl cpio Ar arg
.It
.Fl ncpio Ar arg
.It
.Fl xdev
.El
.Pp
They all produce errors of one sort or another.
.Pp
If none of the side-effect-producing primitives
.Pf ( Fl exec ,
.Fl ok ,
.Fl print ,
.Fl print0 ,
.Fl printn ,
.Fl count ,
.Fl ls ,
or
.Fl lsf )
are specified, the expression formed by the command line effectively
has parens placed around it, followed by
.Fl print .
.Sh PATTERNS
Patterns for
.Fl name
and
.Fl path
are modeled somewhat after shell glob patterns, but there are important
differences.  A pattern is formed from plain characters (anything not
listed below), which match themselves, and various special characters:
.Bl -tag -width indent
.It \&?
Matches any single character.
.It \e Ns Ar c
Matches
.Ar c ,
even if it is a character that would normally have other meaning (such
as
.Sq \&? ) .
.It \&*
Matches any string of zero or more characters.
.It \&[ Ns Ar chars Ns No \&]
Matches any one of the
.Ar chars .
A \&] may be included by making it the first character.  Ranges such as
.Sq a-z
are also supported.
.El
.Pp
Notable differences from shell glob patterns include slashes not being
special and the lack of a complement flag in character classes.
.Sh COMPARATORS
Simple comparators are used for numeric quantities such as link count.
A comparator can be a simple number, in which case it matches only if
it exactly equals the relevant property of the object, or a number
preceded by
.Sq \&+
or
.Sq \- ,
in which case it matches when the object's number is greater or less,
respectively, than the number given.
.Pp
A
.Sq time comparator
is similar, but is designed for use with timestamp attributes of
objects, such as the mtime.  A time comparator conceptually consists of
a time interval and a granularity; it matches if the relevant timestamp
of the object is less than, equal to, or greater than the comparator's
(much the way a simple comparator can match on less than, equal to, or
greater then), but with both intervals (the interval specified by the
comparator and the interval from the timestamp to now) first divided by
the granularity.
.Pp
If a time comparator consists of a simple number, possibly prefixed by
a sign (as for any comparator), the granularity is one day, and the
number is in days.  Otherwise, the interval is specified by alternating
numbers and unit letters, as in
.Sq 3d12h ;
it may have a trailing slash and another interval.  If the slash and
second interval are present, the first interval is the comparator's
value, with the second interval specifying the granularity; otherwise,
the granularity is one of the smallest unit explicitly mentioned in the
comparator's interval.  The unit letters and their meanings are:
.Bl -tag -width indent
.It y
.Sq Years .
The unit is 31556952 seconds (the mean Gregorian year of 365.2425
days).
.It m
.Sq Months .
The unit is 2629746 seconds (one twelfth of a mean year).  Note that
this is not equal to any calendar month; it is not even an integer
number of days.
.It w
.Sq Weeks .
The unit is seven days, 604800 seconds.
.It d
.Sq Days .
The unit is one day, 86400 seconds.
.It h
.Sq Hours .
The unit is one hour, 3600 seconds.
.It m
.Sq Minutes .
The unit is one minute, 60 seconds.
.It s
.Sq Seconds .
The unit is one second.
.El
.Pp
When given, they must appear in the above order, from largest to
smallest
.Pf ( Sq 3d6h
is acceptable,
.Sq 6h3d
is not).  The letter
.Sq m
is used for both months and minutes; because of the ordering
requirement, if weeks, days, or hours are mentioned, or if both months
and minutes are given, there is no ambiguity.  If years are mentioned
but not seconds, it is taken as months; if seconds are mentioned but
not years, minutes.  If none of the foregoing disambiguate, an error
occurs.
.Pp
A time comparator can also be the word "future", in which case it
matches any time which is in the future.  When this is done,
.Nm
takes care to avoid getting confused by time changes after it starts
but before the test is done (such timestamps are not considered to be
in the future).
.Pp
For example,
.Dl -mtime +3w/1d
matches if the modify time is 22 days or more in the past (that is, if
the time from last modification to now, divided by 86400, is strictly
greater than 21).  The same thing could be written
.Dl -mtime +21d
where there is no need for a granularity spec.  Writing
.Dl -mtime +3w
would put the cutoff at 28 days (just under four weeks), because the
granularity would be one week.
.Pp
When dealing with times in minutes, be careful of the granularity
defaults.  Writing
.Dl -mtime +5m0s
uses a granularity of one second, not the one minute that you might
have intended.  This can be avoided by disambiguating differently, as in
.Dl -mtime +0h5m
or by specifying an explicit granularity, as in
.Dl -mtime +5m0s/1m0s
.Sh SEE ALSO
.Xr find 1 ,
.Xr stat 2 ,
.Xr getpwent 3 ,
.Xr getgrent 3 ,
.Xr getpwuid 3 ,
.Xr getgrgid 3
.Sh BUGS
It can be difficult to safely script
.Nm
because of the poorly-specified definition of the boundary between
directories to search and the expression.
.Pp
The unimplemented primitives occasionally would be useful.
.Sh AUTHOR
Mouse,
.Aq mouse@rodents-montreal.org .