Man Linux: Main Page and Category List

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.

                                 name ( arguments )
       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

       Peter Miller   E-Mail:   millerp@canb.auug.org.au
       /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/