TW(1)

NAME
tw - file tree walk

SYNOPSIS
tw [ -imnpqHILPX ] [ -a args ] [ -c argcount ] [ -d dir ] [ -e expr ] [ -f find ] [ -s cmdsize ] [ -F codes ] [ -G code-format ] [ -S separator ] [ - ] cmd [ arg ... ]

DESCRIPTION
tw recursively descends the file tree rooted at the current directory and lists the pathname of each file found. If cmd arg ... is specified then the pathnames are collected and appended to the end of the arg list and cmd is executed as if execvp(2) were used. cmd may be executed more than once if the combined size of the pathnames exceeds system argument limits. If -f find is specified then the fast find pattern find is used to match pathnames rooted at . or the -d directories from the fast find list that is updated each night. Files that do not currently exist and files created since the list was last updated are silently ignored. Fast find is enabled by the presence of the find.codes list in /usr/local/share/lib/find or /usr/lib/find or a valid list pointed to by the environment variable FINDCODES. Public fast find list updates require sufficient privelege and are usually done nightly by the local administrator. If the last option is - and -f find was not specified then the pathnames are read, one per line, from the standard input. For - the -d dir options are ignored and directories are not recursively traversed. The options are:

-a args
    The first arg named args is replaced by the current pathname list before cmd is executed.

-c argcount
    cmd is executed after argcount arguments are collected.

-d dir
    The file tree traversal is rooted at dir. Multiple -d directories are traversed in order from left to right. If the last option was - then the -d options are ignored.

-e expr
    expr defines expression functions that control the tree traversal. Multiple -e expressions are parsed in order from left to right. Expression syntax is described below. The expression functions are:

    Evaluated for each file in which
        returns non-zero. The default lists each selected file, one per line, on the standard output.

    Evaluated once before the traversal begins.
        The return value is ignored.

    Evaluated once after the traversal ends.
        The return value is ignored.

    Evaluated once for each visited file.
        If the return value is non-zero then is evaluated. The default return value is always non-zero.

    Consists of a single file status identifier that
        is used to sort files within directories. before the identifier reverses the sort order. before the identifier ignores case. File status identifiers are described below.

-i  Ignore cmd errors and inaccessible files and directories.

-m  Before visiting a selected file select and visit intermediate directories leading to the file that have not already been selected.

-n  Evaluate the and expressions but eliminate the tree traversal. Useful when one of the expressions is an call with a constant expression argument.

-p  A directory is visited after its entries have been processed. Normally directories are visited first.

-q  Emit a query for each visited path. An affirmative response accepts the path, a negative response rejects the path, and a quit response exits tw.

-t  Trace cmd execution.

-H  Enable metaphysical path resolution: symbolic links on the command line are followed, symbolic links encountered in the traversal are not. This is the default.

-I  Ignore case in path comparisons.

-L  Enable logical path resolution: all symbolic links are followed.

-P  Enable physical path resolution: no symbolic links are followed.

-X  Prevent the traversal from crossing mount points.

  Expressions
A function expression is defined by:
        function-name : statement-list
where function-name is one of or and each statement in statement-list is an expr(3) C style expression, including and declarations, and casts, conditionals, and loops, and blocks. The trailing ; in any expression is optional. is assumed when function-name is omitted. The expression value is the value of the last evaluated expression in statement-list. Numbers and comments follow C syntax. String operands must be quoted with either "..." or '...'. String comparisons (== and !=) treat the right hand operand as a ksh(1) file match pattern.

The expressions operate on the current pathname file status that is provided by the following field identifiers, most of which are described under in stat(2):

If  or is the left hand side operand of a binary operator then the right hand side operand may be a string that is interpreted as a tm(3) date expression.

The number of 1k blocks in the file.

The file system type name.
    The default is

If  is the left hand side operand of a binary operator then the right hand side operand may be a string that is interpreted as a group name.

if  is a valid group id in the system database, otherwise.

The depth of the file relative to the traversal root.

An integer valued field associated with each active object in the traversal.
    This field may be assigned. The initial value is 0. Multiple elements may be declared by In this case the field itself is not accessible.

The identifier
    is recognized and can be used to mask the file format and permission bits. If is the left hand side operand of a binary operator then the right hand side operand may be a string that is interpreted as a chmod(1) permission expression.

The current file name with no directory prefix.

The full pathname of the current file.

The file permission bits of
    If is the left hand side operand of a binary operator then the right hand side operand may be a string that is interpreted as a chmod(1) permission expression.

The field as defined in ftwalk(3). This field may be assigned. The symbols and are recognized and correspond to the constants prefixed by may be used to prune subdirectories from the tree traversal.

The file type bits of
    The identifiers and are recognized.

If  is the left hand side operand of a binary operator then the right hand side operand may be a string that is interpreted as a user name.

if  is a valid user id in the system database, otherwise.

An integer variable associated with each unique object visited.
    Objects are identified using the and status fields. This field may be assigned. The initial value is 0. Multiple elements may be declared by In this case the field itself is not accessible.

Field identifiers may be prefixed by 1 or more references, accessing parent directory status information. The parent status information of a top level object is the same as the object except that and are undefined. If a field identifier is immediately preceded by string. then string is a file pathname from which the status is taken.

The following expr(3) functions are also supported:

Causes
    tw to exit with the exit code expr. expr defaults to if omitted.

Print the arguments on
    using the printf(3) specification format. The (short) format modifier is not supported.

Prompt with the
    printf(3) message on for an interactive response. A line beginning with y returns 1, q or EOF causes tw to exit immediately, and any other input returns 0.

EXAMPLES
    tw
Lists the current directory tree.
    tw chmod go-w
Turns off the group and other write permissions for all files in the current directory tree using a minimal amount of chmod(1) command execs.
    tw -e "uid != 'bozo' || (mode & 'go=w')"
Lists all files in the current directory that don't belong to the user or that have group or other write permission.
    tw -m -d / -e "fstype == '/'.fstype && mtime > '/etc/backup.time'.mtime"
Lists all files and intermediate directories on the same file system type as that are newer than the file
    tw - chmod +x < commands
Executes on the pathnames listed in the file
    tw -e "
    int count;
    action:
        count++;
        printf('name=%s inode=%08ld\n', name, ino);
    end:
        printf('%d file%s\n', count, count == 1 ? '' : 's');
    "
Lists the name and inode number of each file and also the total number of files.
    tw -pP -e "
    action:
        if (visit++ == 0) {
            parent.local += local + blocks;
            if (type == DIR) printf('%d\t%s\n', local + blocks, path);
        }
    "
Exercise to the reader.

SEE ALSO
chmod(1), ksh(1), execvp(2), stat(2), expr(3), ftwalk(3), printf(3), tm(3)