NAME¶
aefind - search for files in directory hierarchy
SYNOPSIS¶
aefind [
option... ]
path...
expression
aefind -Help
aefind -VERSion
DESCRIPTION¶
The
aefind command is used to search the combined directory tree of a
change and its project. It is intentionally similar to
find (1),
however it unifies the directory stack of a change and its branch baseline,
and the branch's ancestors' baselines if any.
For each file found in the directory tree, the given expression is evaluated
from left to right, according to the rules of precedence (see the section on
OPERATORS, below), only until the outcome is known, at which point aefind
moves on to the next file name.
If no directory is named on the command line, the current directory is assumed.
Files which have been removed from the project, even if they somehow remain in
the directory tree, will not be reported.
OPTIONS¶
The following options are understood:
- -BaseLine
- This option may be used to specify that the project
baseline is the subject of the command.
- -BAse_RElative
- This option may be used to cause relative filenames to be
considered relative to the base of the source tree. See aeuconf(5)
for the corresponding user preference.
- -CUrrent_RElative
- This option may be used to cause relative filenames to be
considered relative to the current directory. This is usually the default.
See aeuconf(5) for the corresponding user preference.
- -Change number
- This option may be used to specify a particular change
within a project. See aegis(1) for a complete description of this
option.
- -Help
-
This option may be used to obtain more information about how to use the
aefind program.
- -Project name
- This option may be used to select the project of interest.
When no -Project option is specified, the AEGIS_PROJECT
environment variable is consulted. If that does not exist, the user's
$HOME/.aegisrc file is examined for a default project field (see
aeuconf(5) for more information). If that does not exist, when the
user is only working on changes within a single project, the project name
defaults to that project. Otherwise, it is an error.
- -Resolve
- This option may be used to request that filenames be
absolute paths, referring to the fully resolved file name. This is the
default.
- -No_Resolve
- This option may be used to request that filenames be base
relative names, relative to the root of the “stacked”
directory tree.
- -Verbose
- This option may be used to request that the expression be
printed again on the standard output. This is the expression as understood
by aefind, to assist you in ensuring that you and the command
agree. The expression is fully parenthesized, and all implicit operators
made explicit. Where possible, constant expressions will have been
folded.
See also
aegis(1) for options common to all aegis commands.
All options may be abbreviated; the abbreviation is documented as the upper case
letters, all lower case letters and underscores (_) are optional. You must use
consecutive sequences of optional letters.
All options are case insensitive, you may type them in upper case or lower case
or a combination of both, case is not important.
For example: the arguments "-project, "-PROJ" and "-p"
are all interpreted to mean the
-Project option. The argument
"-prj" will not be understood, because consecutive optional
characters were not supplied.
Options and other command line arguments may be mixed arbitrarily on the command
line, after the function selectors.
The GNU long option names are understood. Since all option names for
aefind are long, this means ignoring the extra leading '-'. The "
--option=value" convention is also
understood.
EXPRESSIONS¶
The expression is made up of basic elements, tests (which return a true or false
value), and actions (which have side effects and return a true or false
value), all separated by operators.
BASIC ELEMENTS¶
- {}
- The value of this expression is the file name of the file
currently being considered. The value is affected the the -Resolve
option.
- {-}
- The value of this expression is the file name of the file
currently being considered, relative to the base of the directory
stack.
- {+}
- The value of this expression is the absolute path of the
file currently being considered.
- number
- Numbers may be specified directly, for use with other tests
and operators. In the style of C, they may be hexadecimal with a
“0x” prefix, octal with a “0” prefix, or decimal
otherwise.
- string
- Strings may be specified directly, for use with other tests
and operators. If the string contains shell meta-characters, you may need
to quote it.
- -FAlse
- The value of this expression is always false.
- -NOW
- The value of this expression is the current time, at the
start of execution.
- -TRue
- The value of this expression is always true.
OPERATORS¶
The
-and operator is assumed where the operator is omitted. You will need
to quote many of the operators, to protect them from interpretation by the
shell. Each operator must be a separate command line argument.
- ( expr )
- Force precedence.
- + expr
- Unary plus. Is is an error if the argument cannot be
coerced to a number.
- - expr
- Unary minus. Result is the numeric negative of the
argument. Is is an error if the argument cannot be coerced to a
number.
- ! expr
- Logical negation of the sense of the expression. Is is an
error if the argument cannot be coerced to a boolean.
Synonym: -Not
- ~ expr
- Bitwise not of the argument. Is is an error if the argument
cannot be coerced to an integer.
- expr1 * expr2
- This operation multiplies the two values. Is is an error if
the arguments cannot be coerced to numbers.
- expr1 / expr2
- This operation divides the argument value by the second. Is
is an error if the arguments cannot be coerced to numbers. Is is an error
if the second argument is zero.
- expr1 % expr2
- This operation produces the remainder of the division of
the first argument by the argument. Is is an error if the arguments cannot
be coerced to numbers. Is is an error if the second argument is zero.
- expr1 ~ expr2
- Is is an error if the arguments cannot be coerced to
strings. Is is an error if the first argument is not a valid pattern. The
first argument is the pattern, and the second is the string The result is
true if the pattern matches, and false if it does not. This operation
performs a shell file pattern comparison. to be compared.
- expr1 + expr2
- This operation adds the two values. Is is an error if the
values cannot be coerced to numbers.
- expr1 - expr2
- This operation subtracts the second values from the first.
Is is an error if the values cannot be coerced to numbers.
- expr1 ## expr2
- This operation concatenates the arguments. Is is an error
if the arguments cannot be coerced to strings. (Note: this is not
the same as the : operator of the expr(1) command.)
- expr1 << expr2
- Shift the first argument left by the number of bits
specified by the second argument. The left argument is treated as an
unsigned number. Is is an error if the values cannot be coerced to
numbers.
- expr1 >> expr2
- Shift the first argument right by the number of bits
specified by the second argument. The left argument is treated as an
unsigned number. Is is an error if the values cannot be coerced to
numbers.
- expr1 < expr2
- Compare the values and produce true if the first value is
less than the second value, false otherwise. If both values can be coerced
to numbers, the comparison is numeric; if both values can be coerced to
strings, the comparison is lexicographic; otherwise is it an error.
- expr1 <= expr2
- Compare the values and produce true if the first value is
less than or equal to the second value, false otherwise. If both values
can be coerced to numbers, the comparison is numeric; if both values can
be coerced to strings, the comparison is lexicographic; otherwise is it an
error.
- expr1 > expr2
- Compare the values and produce true if the first value is
greater than the second value, false otherwise. If both values can be
coerced to numbers, the comparison is numeric; if both values can be
coerced to strings, the comparison is lexicographic; otherwise is it an
error.
- expr1 >= expr2
- Compare the values and produce true if the first value is
greater than or equal to the second value, false otherwise. If both values
can be coerced to numbers, the comparison is numeric; if both values can
be coerced to strings, the comparison is lexicographic; otherwise is it an
error.
- expr1 == expr2
- Compare the values and produce true if the first value is
equal to the second value, false otherwise. If both values can be coerced
to numbers, the comparison is numeric; if both values can be coerced to
strings, the comparison is lexicographic; otherwise is it an error.
- expr1 != expr2
- Compare the values and produce true if the first value is
not equal to the second value, false otherwise. If both values can be
coerced to numbers, the comparison is numeric; if both values can be
coerced to strings, the comparison is lexicographic; otherwise is it an
error.
- expr1 & expr2
- This operation produces the bitwise-and of the two values.
Is is an error if the values cannot be coerced to numbers.
- expr1 | expr2
- This operation produces the bitwise-or of the two values.
Is is an error if the values cannot be coerced to numbers.
- expr1 && expr2
- Result is true if both expressions are true. Short circuit
evaluation is used, and so expr2 is not evaluated if expr1
is false. Is is an error if the arguments cannot be coerced to booleans.
Synonym: -And
- expr1 expr2
- Logical and (implied). Result is true if both expressions
are true. Short circuit evaluation is used, and so expr2 is not
evaluated if expr1 is false. Please note that implicit operator
plays merry hell with operator precedence, because there is no operator.
If you are getting odd results, use explicit operators.
- expr1 || expr2
- Result is true if either expression is true. Short circuit
evaluation is used, and so expr2 is not evaluated if expr1
is true. Is is an error if the arguments cannot be coerced to booleans.
Synonym: -Or
- expr1 ? expr2 :
expr3
- The value of this expression is expr2 if
expr1 is true, and expr3 otherwise. The expr1 is
always evaluated, but only one of expr2 or expr3 will be
evaluated. It is an error if the value of expr1 cannot be coerced
to boolean.
- expr1 , expr2
- Both expr1 and expr2 are always evaluated.
The value of expr1 is discarded; the value of the expression is the
value of expr2.
Operators have precedence as described by the following table, highest to
lowest:
Operator |
Direction |
|
(unary) + - ~ ! |
← |
* / % ~ |
→ |
+ - : |
→ |
<< >> |
→ |
< <= > >= |
→ |
== != |
→ |
& |
→ |
^ |
→ |
| |
→ |
&& |
→ |
|| |
→ |
? : |
→ |
, |
→ |
FUNCTIONS¶
There are a number of built-in functions which may be used in the expression.
Functions may be invoked using a syntax similar to C functions.
You need to leave spaces around the parentheses so that they are separate
command line arguments.
- atime
- This function may be used to determine the
last-accessed-time of a file. It takes one argument.
- basename
- This function returns the basename of the string argument
passed to it. It takes one argument.
- ctime
- This function may be used to determine the last-change-time
of an inode. It takes one argument.
- execute
- This function may be used to execute a command. The
arguments are assembled into the command to be executed. Use the special
“{}” argument to insert the name of the current file. The
function returns true of the command's exist status is zero. All following
arguments to find are taken to be arguments to the command until an
argument consisting of `;' is encountered. The command is executed in the
starting directory.
- gid
- This function may be used to determine the gid of a file.
It takes one argument.
- inode
- This function may be used to determine the inode number of
a file. It takes one argument.
- mode
- This function may be used to determine the access mode
(permissions) of a file. It takes one argument.
- mtime
- This function may be used to determine the
last-modified-time of a file. It takes one argument.
- print
- This function may be used to print a value. It takes one
argument. Always returns true.
- size
- This function may be used to determine the size in bytes of
a file. It takes one argument.
- type
- This function may be used to determine the type of a file.
It takes one argument. It returns a string: "block_special",
"character_special", "directory", "file",
"named_pipe", "socket" or
"symbolic_link".
- uid
- This function may be used to determine the uid of a file.
It takes one argument.
TESTS¶
Most tests exist to provide compatibility with
find(1).
- -Access_Minutes [ relative-operator ]
number
- True if the current file was accessed exactly number
minutes ago, false otherwise. If a relative operator is given (<,
<=, ==, !=, > or >=) a relative comparison will be made, rather
than the implicit equality test. This is not identical to the
similar find(1) test. This is shorthand for the “( now -
atime ( {+} )) / 60 relative-operator number”
expression.
- -Access_Time [ relative-operator ]
number
- True if the current file was accessed exactly number
days ago, false otherwise. If a relative operator is given (<, <=,
==, !=, > or >=) a relative comparison will be made, rather than the
implicit equality test. This is not identical to the similar
find(1) test. This is shorthand for the “( now - atime ( {+}
)) / 86400 relative-operator number” expression.
- -Change_Minutes number
- True if the current file's inode was changed exactly
number minutes ago, false otherwise. If a relative operator is
given (<, <=, ==, !=, > or >=) a relative comparison will be
made, rather than the implicit equality test. This is not identical
to the similar find(1) test. This is shorthand for the “( now
- ctime ( {+} )) / 60 relative-operator number”
expression.
- -Change_Time number
- True if the current file's inode was changed exactly
number days ago, false otherwise. If a relative operator is given
(<, <=, ==, !=, > or >=) a relative comparison will be made,
rather than the implicit equality test. This is not identical to
the similar find(1) test. This is shorthand for the “( now -
ctime ( {+} )) / 86400 relative-operator number”
expression.
- -Modify_Minutes number
- True if the current file was modified exactly number
minutes ago, false otherwise. If a relative operator is given (<,
<=, ==, !=, > or >=) a relative comparison will be made, rather
than the implicit equality test. This is not identical to the
similar find(1) test. This is shorthand for the “( now -
mtime ( {+} )) / 60 relative-operator number”
expression.
- -Modify_Time number
- True if the current file was modified exactly number
days ago, false otherwise. If a relative operator is given (<, <=,
==, !=, > or >=) a relative comparison will be made, rather than the
implicit equality test. This is not identical to the similar
find(1) test. This is shorthand for the “( now - mtime ( {+}
)) / 86400 relative-operator number” expression.
- -Newer filename
- True if the current file was modified after the given file.
This is shorthand for the “mtime ( {+} ) > mtime (
filename )” expression.
- -Name pattern
- Base of file name (the path with the leading directories
removed) matches shell pattern pattern. This is short-hand for the
“ pattern ~ basename ( {} )” expression.
- -PAth pattern
- File name matches shell pattern pattern. Note that
the file name if affected by the -resolve option. This is
short-hand for the “ pattern ~ {}” expression.
- -Type string
- The file type matches the type given. This is shorthand for
the “type ( {} ) == string” expression. Type names are
matched similar to options:
Block |
The file is a block special file. |
Character |
The file is a character special file. |
Directory |
The file is a directory. |
File |
The file is a normal file. |
Link |
The file is a symbolic link. |
Pipe |
The file is FIFO (a named pipe). |
Socket |
The file is a UNIX domain socket. |
ACTIONS¶
- -print
- This will print the full file name on the standard output,
followed by a newline. The -Resolve option will affect what is
printed. This is short-hand for the “print ( {} )”
expression.
- -execute string... ;
- The may be used to execute a command. This is short-hand
for the “execute ( string : ... )”
expression.
EXIT STATUS¶
The
aefind command will exit with a status of 1 on any error. The
aefind command will only exit with a status of 0 if there are no
errors.
ENVIRONMENT VARIABLES¶
See
aegis(1) for a list of environment variables which may affect this
command. See
aepconf(5) for the project configuration file's
project_specific field for how to set environment variables for all
commands executed by Aegis.
COPYRIGHT¶
aefind version 4.24.3.D001
Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Peter Miller
The aefind program comes with ABSOLUTELY NO WARRANTY; for details use the '
aefind -VERSion License' command. This is free software and you are
welcome to redistribute it under certain conditions; for details use the '
aefind -VERSion License' command.
AUTHOR¶