xenial (1) aefind.1.gz

Provided by: aegis_4.24.3-3_amd64 bug

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.

        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/