.ig
 Copyright (C) 1993,1994 by the author(s).
 
 This software is published in the hope that it will be useful, but
 WITHOUT ANY WARRANTY for any part of this software to work correctly
 or as described in the manuals. See the ShapeTools Public License
 for details.

 Permission is granted to use, copy, modify, or distribute any part of
 this software but only under the conditions described in the ShapeTools 
 Public License. A copy of this license is supposed to have been given
 to you along with ShapeTools in a file named LICENSE. Among other
 things, this copyright notice and the Public License must be
 preserved on all copies.


Author: Uli Pralle (Uli.Pralle@cs.tu-berlin.de)

$Header: vfind.1[5.0] Tue Jun 29 16:31:49 1993 andy@cs.tu-berlin.de frozen $
..
.TH vfind 1 "Tue Jun 29 16:31:49 1993" "vfind-3.3" "ShapeTools"
.SH NAME
vfind \- find attributed software objects (ASOs)
.SH SYNOPSIS
\fBvfind\fP [\ \fIoptions\fP\ ] \fIpathname-list\ expression\fP
.PP
.SH DESCRIPTION
\fBVfind\fP recursively descends the directory hierarchy for each pathname
in the pathname-list seeking asos that match a boolean expression
written in the primaries given below. In the description, the argument
\fIn\fP is used as a decimal integer where \fI+n\fP means more than
\fIn\fP, \fI\-n\fP means less than \fIn\fP and \fIn\fP means exactly
\fIn\fP.
.SH OPTIONS
.IP "\fB\-version\fP"
print version information about the \fBvfind\fP program itself. No
other action given will be performed.
.IP "\fB\-?, \-help\fP"
print brief instructions about using \fBvfind\fP.
.IP "\fB\-cache\fP"
match a boolean expression also for aso residing in the \fIderived
object cache\fP.
.IP "\fB\-cut\fP \fInesting depth\fP"
causes \fBvfind\fP to descend the filesystem hierarchy down to nesting
depth \fInesting depth\fP.
.IP "\fB\-force\fP"
\fBVfind\fP normally ignores saved asos iff a AtFS directory is a
symbolic link. If the \fB\-force\fP option is given \fBvfind\fP
takes also symbolic AtFS directories into consideration.
.IP "\fB\-hits\fP"
causes \fBvfind\fP to return the number of expressions yielding true
during evaluation.
.IP "\fB\-xdev\fP"
causes \fBvfind\fP not to traverse down into a file system different
from the one on which current argument pathname resides.
.SH PRIMARIES
.IP "\fB\-atime\fP n"
True if the aso has been accessed in \fIn\fP days.
.IP "\fB\-ctime\fP n"
True if status of the aso has been changed in \fIn\fP days.
.IP "\fB\-mtime\fP n"
True if the aso has been modified in \fIn\fP days.
.IP "\fB\-stime\fP n"
True if the aso has been saved in \fIn\fP days.
.IP "\fB\-ltime\fP n"
True if the aso has been locked in \fIn\fP days.
.IP "\fB\-exec\fP command"
True if the executed command returns a zero value as exit status. The
end of the command must be punctated by an ecscaped semicolon. A
command argument `{}' is replaced by the system name of the current aso.
.IP "\fB\-exit\fP n"
Terminates vfind and returns n as the exit status.
.IP "\fB\-vl\fP"
Always true; causes the current aso to be printed together with its
associated statistics. This includes protection mode, \fIAtFS\fP version
state, user, host, size in bytes, modification time respectively
saving time. The format is identical to that of ``vl -l''.
.IP "\fB\-name\fP name"
True if the name argument matches the filename component of the
current aso. Normal Shell argument syntax may be used if escaped.
.IP "\fB\-perm\fP onum"
True if the aso permission flags exactly match the octal numer
\fIonum\fP. If \fIonum\fP is prefixed by a minus sign, more flag bits
(017777) become significant and the flags are compared:
\fI(flags&onum)==onum\fP.
.IP "\fB\-print\fP"
Always true; causes the relative path of the current aso to be printed.
.IP "\fB\-prune\fP"
Always true; has the side effect of pruning the tree, iff the current file 
is a directory.
.IP "\fB\-SinceName\fP name"
True if the current aso is older than the corresponding aso having
the symbolic name \fBname\fP.
.IP "\fB\-symbolic\fP name"
True if the current aso has the symbolic name \fIname\fP. See \fBvadm(1)\fP
or \fBsave(1)\fP on how to attach a symbolic name to an aso.
.IP "\fB\-state\fP state"
True if the state of the current aso matches state
\fIstate\fP, where \fIstate\fP is \fBbusy\fP, \fBsave\fP, \fBproposed\fP,
\fBpublished\fP, \fBaccessed\fP, or \fBfrozen\fP.
.IP "\fB\-type\fP c"
True if the type of the current aso is \fIc\fP, where c is \fBb\fP, \fBc\fP,
\fBd\fP, \fBf\fP, \fBl\fP, or \fBs\fP for block special file,
character special file, directory, plain file, symbolic link, or socket.
.IP "\fB\-uda\fP uda"
True if the current \fBaso\fP has an user defined attribute matching
uda \fIuda\fP, where \fIuda\fP is of the form \fIname[=value]\fP.
.IP "\fB\-user\fP user"
True if the current aso belongs to user \fIuser\fP, where \fIuser\fP is a
login name optinally followed by a domainname (e.g. uli@cs.tu-berlin.de).
.IP "\fB\-last\fP"
True if the current aso is the last version of the development line.
.IP "\fB\-first\fP"
True if the current aso is the first version of the development line.
.IP "\fB\-locked\fP"
True if the current aso is locked.
.IP "\fB\-locker\fP user"
True if the current aso is locked by user \fIuser\fP, where
\fIuser\fP is a login name optionally followed by a domainname.
.IP "\fB\-eq\fP vnum"
True if the version number of the current aso matches version number
\fIvnum\fP, where \fIvnum\fP is \fIgeneration.revision\fP.
.IP "\fB\-lt\fP vnum"
True if the version number of the current aso is less than the version number
\fIvnum\fP.
.IP "\fB\-le\fP vnum"
True if the version number of the current aso is less equal than the
version number \fIvnum\fP.
.IP "\fB\-gt\fP vnum"
True if the version number of the current aso is greater than the
version number \fIvnum\fP.
.IP "\fB\-ge\fP vnum"
True if the version number of the current aso is greater equal than the
version number \fIvnum\fP.
.IP "\fB\-newer\fP file"
True if the current aso is more recently than the argument file which can
be an aso (e.g. vfind.c[1.6]).
.IP "\fB\-size\fP n"
True if the file is n blocks long (512 bytes per block).
.PP
The primaries may be combined using the operators \fB(\fP, \fB)\fP for
grouping, \fB!\fP for negation, \fB\-a\fP for concatenation (may be
omitted) and \fB-o\fP for alternation of primaries. Parentheses and
the exclamation mark are special to the Shell and must be escaped.
.PP
\fBvfind\fP does not descent AtFS directories, so the AtFS
archives are never selected.
.SH EXAMPLES
.PP
To find all asos whose state is busy and that have the symbolic
name "foobar":
.IP
vfind / \-state busy \-symbolic foobar \-print
.IP
.PP
To find the latest proposed version of foo.c in the current directory:
.IP
vfind -prune 0 . -name foo.c -state proposed -last -print
.IP
.SH SEE ALSO
vl(1), find(1)
.SH INCOMPATIBILITIES
The following \fBfind(1)\fP primaries are not recognized or implemented:
-link, -nouser, -group, -nogroup, -inum, and -ok.
.SH AUTHOR
Uli.Pralle@cs.tu-berlin.de
.br
Steve Emerson (steve@unidata.ucar.edu) contributed the primary
\&'SinceName'.