RFIND(1) RFIND(1)
NAME
rfind - remote find
SYNOPSIS
rfind [-debug] file-system search-expression
DESCRIPTION
rfind is a fast, client-server adaptation of the find(1) command. It
maps the specified file-system name to a host machine, and submits the
search-expression to the rfindd(1M) daemon running on that host, for
evaluation over the specified file-system. The rfindd(1M) daemon
searches side files for the requested information, and returns it to
rfind(1) for display on stdout. These side files were previously created
by the fsdump(1M) command, and contain information about a particular
file-system
If the -debug option is specified, then rfind will display the result of
parsing the file-system and search-expression on stdout.
File-System
The file-system to be searched may be specified in one of three forms:
canonical, alias or local path. Only one file-system may be specified.
Remaining arguments are considered to be part of the search-expression.
If the file-system argument contains a colon ':' character, then it is
considered to be in canonical form. The portion of the name before the
first ':' is taken as the network hostname, and the remaining characters
after this ':' are taken as the full pathname of the file system subtree
to searched. For example, the command:
rfind bonnie.wpd:/cypress/att/usr/src foo.c
will send a request to the rfindd(1M) daemon on the host bonnie.wpd, to
search for the file foo.c below the directory /cypress/att/usr/src
(staying within whatever file system contains this path).
If the file-system argument does not contain a ':' character, then a list
of standard locations is searched in an attempt to resolve the file-
system as an alias. Four places are searched, in order:
1) the file referenced by the RFINDALIASES environment variable, if any
2) the file /etc/rfind.aliases
3) the NIS (Yellow Pages) map called rfind.aliases
4) a hardwired internal list which aliases "root" and "usr" to
"localhost:/" and "localhost:/usr", respectively.
The first of these places to specify a mapping for the file-system alias
is used. See the comments in the file /etc/rfind.aliases for a
description of that file's format.
Page 1
RFIND(1) RFIND(1)
If the file-system argument is neither in canonical form nor an alias,
then it is considered to be a local path to either an EFS, XFS or NFS
directory or other file. The path need not begin with a slash. Any
referenced symbolic links are fully resolved where possible to their
final target.
The inode named by the local path is examined. If it resides on an "efs"
or "xfs" file system, then the request is sent to rfindd(1M) on the
localhost for resolution. If it resides on an "nfs" file system, then
the file /etc/mtab is examined to determine the hostname of the server to
send the request to. For example, the command:
rfind /cypress/att/usr/src foo.c
will, in the case that bonnie.wpd:/cypress is mounted to /cypress (or, if
/cypress is a symlink, to the target of that symlink), send the same
request as the previous example. If the named inode is in an automounted
(see automount(1M)) file system, then that file system will be
automounted if it wasn't already. The local mount point need not be
isomorphic with the server's pathname for this file system.
If none of these mechanisms succeeds, then rfind(1) displays a list of
all known aliases on its error output and exits with non-zero status.
Search-Expression
rfind accepts a boolean search-expression, written in the primaries given
below, that has a syntax similar to that of the find(1) command.
In the descriptions, the argument n is used as a decimal integer where +n
means strictly greater than n, -n means strictly less than n and n means
exactly n. Valid expressions are:
-name file True if file matches as many trailing components of the
current file's pathname as are specified in the pattern
file. The wildcard characters [, !, -, ? and * may be
used to specify filename patterns. See the section File
Name Generation of sh(1) for their usage. If the first
character of file is the slash / character, then all
components of the current file's pathname must match.
-root path True if the current file is located in the file-system
hierarchy somewhere under the directory specified by
path. If path specifies a file that is not a directory,
then this primary is true for just that specified file.
-perm [-]onum True if the file permission flags exactly match the octal
number onum (see chmod(1)). If onum is prefixed by a
minus sign, only the bits that are set in onum are
compared with the file permission flags, and the
expression evaluates true if they match.
Page 2
RFIND(1) RFIND(1)
-type c True if the type of the file is c, where c is b, c, d, l,
p, f, or s for block special file, character special
file, directory, symbolic link, fifo (a.k.a named pipe),
plain file, or socket respectively.
-links n True if the file has n links.
-user uname True if the file belongs to the user uname. If uname is
numeric and does not appear as a login name in the
/etc/passwd file, it is taken as a decimal user ID.
-group gname True if the file belongs to the group gname. If gname is
numeric and does not appear in the /etc/group file, it is
taken as a decimal group ID.
-size n[c] True if the file is n blocks long (512 bytes per block).
If n is followed by a c, the size is in characters.
-inum n True if n is the inode number of the file. If -inum is
used to display a single inode (that is, if the n inode
number specified is not prefixed with a + or -), and if
the current inode has multiple links, then the pathname
of only one of the links is available for printing.
-atime n True if the file has been accessed in n days (see stat(2)
for a description of which file operations change the
access time of a file).
-mtime n True if the file has been modified in n days (see stat(2)
for a description of which file operations change the
modification time of a file).
-ctime n True if the file has been changed in n days (see stat(2)
for a description of which file operations change the
change time of a file).
-print Always true; causes the current path name to be printed.
-ls Always true; causes current pathname to be printed
together with its associated statistics. These include
(respectively) inode number, protection mode, number of
hard links, user, group, size in bytes, and modification
time. If the file is a special file the size field will
instead contain the major and minor device numbers. If
the file is a symbolic link the pathname of the linked-to
file is printed preceded by ->. The format is identical
to that of ls -lid, however the formatting is done
internally, without executing the ls program.
-printf format Always true; causes information about the current file to
be printed using the specified format. The format is a
character string that contains three kinds of objects:
Page 3
RFIND(1) RFIND(1)
1) plain characters, which are simply copied to the
output stream, 2) the C-like escape sequences \b, \f, \n,
\r, \t and \v, which are converted (see echo(1) for their
meaning), and 3) conversion specifications, each of which
results in displaying in decimal or string form the value
of a particular attribute of the current file. The
conversion specifications recognized are described below
in the section Printf Format.
-ncheck n True if n is the inode number of the current file.
Causes the inode number and full pathname for each link
to the current file to be displayed in the fixed format
"%i\t%P\n" for each link to the current file. The output
resembles that from the ncheck(1) command.
-none Always true; suppresses the default -print operator in
the case that none of the operators -ls, -print, -printf,
or -ncheck were supplied.
-newer path True if the current file has been modified more recently
than the argument path. The file specified by path must
be root based, and reference a file within the file-
system that is being searched. See stat(2) for a
description of which file operations change the
modification time of a file.
-anewer path True if current file has been accessed more recently than
the argument path. The file specified by path must be
root based, and reference a file within the file-system
that is being searched. See stat(2) for a description of
which file operations change the access time of a file.
-cnewer path True if current file has been changed more recently than
the argument path. The file specified by path must be
root based, and reference a file within the file-system
that is being searched. See stat(2) for a description of
which file operations change the change time of a file.
-depth Always true; causes descent of the directory hierarchy to
be done so that all entries in a directory are acted on
before the directory itself.
-prune Always true; has the side effect of pruning the search
tree at the current file. If the current path name is a
directory, rfind will not descend below directory.
-follow Always true; causes the underlying file of a symbolic
link to be checked rather than the symbolic link itself.
-showdots Always true; causes the conventional "." and ".." entries
of each directory to become visible. Normally these
entries are suppressed unless explicitly named by path or
Page 4
RFIND(1) RFIND(1)
inode number.
-changed True if executing the stat(2) system call from the
rfindd(1M) daemon on the full pathname of the current
file yields a result that does not have the same file
type, modification time, change time and size values as
were observed for the current file when it was last
examined by fsdump(1M). In the case that the current
file is a directory, then the logic of the -changed
operator is optimized for use by ptools(1), a software
source control tool used internally by Silicon Graphics,
and involves executing the stat(2) system call for every
directory that contains any link (hard or symbolic) of
any file contained within the current directory.
-newdiradd format
True if executing the stat(2) system call from the
rfindd(1M) daemon on the full pathname of the current
file yields a result that does not have the same file
type, modification time, change time and size values as
were observed for the current file when it was last
examined by fsdump(1M) and that it is a directory which
contains subdirectories which previously did not exist or
were of a different type. The information about these
directories is printed using the specified format.
-stcount Always true; subtree count - increments running subtree
total by a count of one. The subtree options are
described below in the section Subtree Options.
-stsize Always true; subtree size - increments running subtree
total by the number of blocks in the current file. The
subtree options are described below in the section
Subtree Options.
-sttotal threshold
True if the running subtree total exceeds the specified
decimal threshold, or if the running subtotal is non-zero
and the current path being evaluated is the final, root
path. If true, copies the running subtotal to the
aggregate subtotal, and zeros the running subtotal. The
subtree options are described below in the section
Subtree Options.
-exit status If executed during the course of evaluating the search-
expression, causes rfind(1) to exit immediately with the
specified decimal status.
( expression ) True if the parenthesized expression is true (parentheses
are special to the shell and must be escaped).
Page 5
RFIND(1) RFIND(1)
The primaries may be combined using the following operators (in order of
decreasing precedence):
1) The negation of a primary (! is the unary not operator).
2) Concatenation of primaries (the and operation is implied by the
juxtaposition of two primaries). The and operator may also be
specified as -a.
3) Alternation of primaries (-o is the or operator).
Printf Format
This section describes the conversion specifications accepted by the
-printf format option. Each conversion specification consists of the
character % and a single following conversion character. Numeric
quantities are output in decimal, except for permissions, which are
octal.
The conversion specifications and their meanings are:
%a,%c,%m The access (atime), change (ctime) or modification (mtime) time
stamps for the current file, as seconds since the epoch.
%u,%g The numeric user (uid) or group (id) for the current file.
%p The octal permissions (mode, including type) for the current
file.
%n The number of links to the current file.
%i The inode number of the current file.
%s The size in bytes of the current file.
%e The NFS internal generation number (gen) of the current file.
%d For block and character special files, the major/minor device
(rdev) of the current file. For other file types, this is
zero.
%x For directory and regular files, the number of EFS extents.
For other file types, this is zero.
%N The actual number of links observed when fsdump(1M) traversed
the file-system. This will usually be the same value as for
%n, above, unless either a concurrent update caused
inconsistent data to be captured (rare but allowed), or
fsdump(1M) lacked permissions to scan part of the directory
structure (in which case, inode contents are still available,
but names are not). The fsdump(1M) command runs setuid root
only long enough to obtain a read only file descriptor on the
target file-system in order to read inode contents, then
Page 6
RFIND(1) RFIND(1)
restores its invoker's privileges.
%E For directories, the number of directory entries observed when
fsdump(1M) traversed the file-system.
%S The number of active inodes below this inode in the file-system
hierarchy. This value is only non-zero for directories. The
conventional "." and ".." directory entries are included in
this count.
%I The total number of active inodes in the file-system.
%M The pathname of the mount point on which the current file-
system was mounted when fsdump examined it.
%Q One of the "file environment" attributes: a quick and dirty
checksum of just the first 8 bytes of each 512 block of the
file, plus the inode number of the file.
%Y One of the "file environment" attributes: If the current file
is a symbolic link, displays the path contained in the link
file. If the file is not a symbolic link, or its contents
could not be read by fsdump(1M), then displays the empty
string.
%U Aggregate subtree total - see further the section Subtree
Options.
%R One of the "file environment" attributes: the top-of-trunk RCS
delta number. This value is maintained for files that appear
to be RCS ,v files, and is the empty string for other files.
%T One of the "file environment" attributes: the top-of-trunk RCS
date stamp. This value is maintained for files that appear to
be RCS ,v files, and is the empty string for other files.
%L One of the "file environment" attributes: the user name of the
locker of locked RCS ,v files. For any other file, this is the
empty string.
%A One of the "file environment" attributes: the user name of the
author of the RCS top-of-trunk delta. For other files, this is
the empty string.
%D The pathname of the directory containing the current file, or
dirname.
%B The basename of the current file.
%P The full pathname of the current file.
Page 7
RFIND(1) RFIND(1)
%W The canonical full pathname of the current file. If the file-
system argument to rfind passes through a symlink, then the
"%P" format will show you a pathname relative to the path
provided in the file-system argument, whereas "%W" will show
you the canonical pathname, free of symlinks.
%Z The full pathname of the new subdirectory within the current
file.
%% Same as %.
Subtree Options
The -stcount, -stsize and -sttotal options, together with the -printf
"%U" format, provide a mechanism to group subtrees of the searched tree
by sizes or counts. The -sttotal option implies the -depth option. The
rfind command maintains two internal values, the running subtotal and the
aggregate subtotal. Both values are initialized to zero.
The running subtotal is maintained during the recursive depth first
search so that for directories it is always the total values not already
aggregated for the subtree below the directory, and for other files, it
is always the value for just that file. The aggregate subtotal is reset
to zero before evaluating the search-expression for each file.
Whenever the -stcount option is evaluated, it increments the running
subtotal by one.
Whenever the -stsize option is evaluated, it increments the running
subtotal by the size in blocks of the current file.
Whenever, for an individual file or for a subtree, the -sttotal option is
evaluated and the current running subtotal exceeds the threshold
specified on the -sttotal option, then the running subtotal is copied to
the aggregate subtotal, and the running subtotal is reset to zero. When
evaluating the search-expression for the final (top) directory of the
search (namely, the directory specified or implied by the -root option),
the -sttotal option copies any non-zero running subtotal to the aggregate
subtotal, even if it does not exceed the specified threshold, and
evaluates as true if a copy was done.
The -printf "%U" format displays the current value of the aggregate
subtotal.
These options are intended to be used together. Typically one of either
the -stcount or -stsize option is used to increment the running subtotal,
along with the -sttotal option to copy the running subtotal to the
aggregate subtotal whenever the threshold is reached, along with the
-printf "%U" format to display the aggregate subtotal.
For example, one could determine where, in a large RCS based source tree,
the recent (say, in the last day) changes to RCS/*,v files were
clustered, with the command:
Page 8
RFIND(1) RFIND(1)
rfind cypress 'RCS/*,v' -mtime -1 -stcount -o -type d -sttotal 10
-printf "%U\t%P\n"
The output from the above command might look like:
14 /cypress/att/usr/src/cmd/motif/clients/4Dwm/RCS
13 /cypress/att/usr/src/cmd/motif/sgi/book
12 /cypress/att/usr/src/cmd/X11R4/mit/fonts.pcf/bdf/75dpi/RCS
16 /cypress/att/usr/src/cmd/X11R4/mit
17 /cypress/att/usr/src/cmd/demo
14 /cypress/att/usr/src/cmd
11 /cypress/att/usr/src/man
10 /cypress/att/usr/src/gfx/lib/libgl/LIGHT/asmgfx/RCS
11 /cypress/att/usr/src/gfx/lib/libgl/LIGHT/cgfx/RCS
14 /cypress/att/usr/src/gfx
32 /cypress/att/usr/src
10 /cypress/bsd/src/etc/timed/RCS
1 /cypress
The above output shows the several subtrees containing 10 or more changed
RCS/*,v files, with the number of such files in the first column.
For another example, one could determine where disk space was being used
on the root file system with the command:
rfind root -stsize -sttotal 1000 -printf "%U\t%P\n"
This command produces output like the following:
1374 /bin/wsh
1201 /bin/news_server
4991 /bin
3551 /etc/gl
3651 /etc
2192 /stand/ide
2817 /unix
1961 /
From this output, one can see that three individual files, /bin/wsh,
/bin/news_server and /unix, exceeded the 1000 block threshold, that most
of the remaining disk space is in use by files under the directories
/bin, /etc/gl, /etc and /stand/ide, and that 1961 blocks of data resides
somewhere else on the root file system.
Defaults
To make interactive use easier, rfind supports several default options
and primaries in the search-expression.
1) A default leading option of -root /rootpath is supplied, where
/rootpath is the mount point implied by the first argument to rfind.
Page 9
RFIND(1) RFIND(1)
2) The search-expression is parsed from left to right in two phases.
3) Unexpected arguments in the first phase that begin with the '/'
character are supplied a default -root option.
4) The -root path primaries constructed during the first phase are
automatically separated from each other by the -o operator.
5) The first phase ends at the first argument that is neither an
explicit -root nor starts with the '/' character.
6) At the end of the first phase, an automatic opening ( parenthesis is
inserted, so that the entire list of -o separated roots just built is
concatenated (implying the -a operator) with the expression resulting
from the second phase.
7) Unexpected arguments in the second phase that do not begin with the
'-' character are supplied a default -name option.
8) At the end of the second phase, sufficient closing ) parentheses are
supplied to match any unmatched opening ( parentheses.
9) Finally, if none of the operators -ls, -print, -printf, -none or
-ncheck appeared, a default -print operator is supplied.
The result of the above defaults is that the command:
rfind cypress ed.c
is automatically expanded into the equivalent command:
rfind cypress -root /cypress -a \( -name ed.c \) -print
and that the command:
rfind bugs /d1/Bugs /d1/alphabugs 1234
is automatically expanded into the command:
rfind bugs -root /d1 -a \( -root /d1/Bugs -o -root /d1/alphabugs \)
-a \( -name 1234 \) -print
Performance
The rfindd (1M) daemon dynamically selects from several available search
strategies in order to provide optimum performance.
1) The -root path option may be used to specify a small portion of the
file-system to be searched.
2) The -name file option may take advantage of a secondary sort index by
file basename. The first wildcard character [, ? or * in the
basename of the provided name terminates the portion of the basename
Page 10
RFIND(1) RFIND(1)
which is used to restrict the search.
3) If the -inum n or -ncheck n options are used, then direct and rapid
lookup is possible.
4) If the either of the options -prune or -depth are used, then this
disables the above search strategies (2) by name and (3) by inode
number.
Small searches that are able to take advantage of one of the above search
strategies often complete in less than 1 second. Large searches that
require walking a large tree can take up to several minutes, depending
primarily on server performance.
The selection of search strategy is based on dynamically computed
weights, so two rfind(1) commands that are syntactically identical may be
accomplished by different strategies depending for example on the
relative size of the subtrees specified by -root path options and the
relative portion of the name space covered by -name file options.
The order of output is dependent on the search order. In the case that
the secondary sort index by file basename is used, the output will not
appear to have any particular order.
Comparison to find(1)
The rfind(1) has the following new options that are not available in the
find(1) command: -root, -ls, -printf, -none, -ncheck, -showdots,
-stcount, -stsize, -sttotal, -changed and -exit.
The following find(1) options are not available in rfind(1): -cpio, -ok,
-exec, -local and -mount. Since the preferred way to create cpio
archives is to use the cpio(1) command itself, perhaps receiving
filenames via a pipe from the find(1) command, it did not seem worthwhile
to maintain the obsolete variant of cpio that is embedded in the find(1)
command. Since the rfind(1) uses rpc(3R) with minimal authentication,
the -ok and -exec options would have presented unacceptable security
compromises. Since the rfind(1) command only works on a single file-
system, the -local and -mount options are effectively always on.
The find(1) searches in realtime on multiple file systems, whereas
rfind(1) searches the previously created side file of a single file
system.
The find(1) command is a single process utility, whereas the rfind(1)
command is the frontend of client-server utility.
Searching a large file system is many times faster with rfind(1) than
with find(1).
The -name file option of rfind(1) supports multiple components in the
pattern file.
Page 11
RFIND(1) RFIND(1)
The command line defaults simplify the use of rfind(1).
Examples
To find all files named 'find*' in Cypress:
rfind cypress 'find*'
To display all character special devices on the root file system except
those under any dev directory:
rfind root -type d -name dev -prune -o -type c -print
To find all symbolic links that point off the current file system (or
point nowhere):
rfind cypress -follow -type l
To display the grand total number of blocks contained in all files and
(recursively) directories within a directory subtree rooted at $P, where
$P is the canonical (symlink free) absolute (root based) path to the top
of the subtree:
rfind $P -stsize $P -sttotal 1 -printf "%U\t%P\n"
The output of the above command is similar to the output of:
du -s $P
FILES
/etc/rfind.aliases List of file-system mappings.
/etc/passwd UID information supplier
/etc/group GID information supplier
SEE ALSO
chmod(1), cpio(1), echo(1), find(1), fsdump(1M), ncheck(1), rfindd(1M),
sh(1), test(1).
stat(2), umask(2), rpc(3R), fs(4).
BUGS
Do not use the -prune option with either of the -depth or -sttotal
options, because the alternative tree walk order used by these options
confuses the logic of the -prune option, causing the wrong file-system
subtree to be pruned.
Page 12