XARGS(1V)

NAME
xargs - construct the arguments list(s) and execute a command

SYNOPSIS
xargs [ -ptx ] [ -eeofstr ] [ -ireplstr ] [ -lnumber ] [ -nnumber ] [ -ssize ] [ command [initial-arguments ] ]

AVAILABILITY

This command is available with the System V software installation option. Refer to for information on how to install optional software.

DESCRIPTION

xargs combines the fixed initial-arguments with arguments read from the standard input, to execute the specified command one or more times. The number of arguments read for each command invocation, and the manner in which they are combined are determined by the options specified.

command, which may be a shell file, is searched for using one's $PATH. If command is omitted, /usr/bin/echo is used.

Arguments read in from the standard input are defined to be contiguous strings of characters delimited by white space. Empty lines are always discarded. Blanks and tabs may be embedded as part of an argument if they are escaped or quoted. Characters enclosed in quotes (single or double) are taken literally, and the delimiting quotes are removed. Outside of quoted strings, a `\' (backslash) will escape the character it precedes.

Each arguments-list is constructed starting with the initial-arguments, followed by some number of arguments read from the standard input (Exception: see the -i option). Options -i, -l, and -n determine how arguments are selected for each command invocation. When none of these options are coded, the initial-arguments are followed by arguments read continuously from the standard input until an internal buffer is full, and then command is executed with the accumulated arguments. This process is repeated until there are none left. When there are option conflicts (for instance, -l versus -n), the last option takes precedence.

xargs will terminate if it receives a return code of -1, or if it cannot execute command. When command is a shell script, it should explicitly exit (see sh(1)) with an appropriate value to avoid accidentally returning with -1.

OPTIONS

-p  Prompt mode. The user is asked whether to execute command each invocation. Trace mode (-t) is turned on to print the command instance to be executed, followed by a ?... prompt. A reply of y (optionally followed by anything) will execute the command; anything else, including just a return, skips that particular invocation of command.

-t  Trace mode. The command and each constructed argument list are echoed to file descriptor 2 just prior to their execution.

-x  Terminate xargs if any argument list would be greater than size characters; -x is forced by the options -i and -l. When neither of the options -i, -l, or -n are coded, the total length of all arguments must be within the size limit.

-eeofstr
    eofstr is taken as the logical EOF string. `_' (underbar) is assumed for the logical EOF string if -e is not coded. The value -e with no eofstr coded turns off the logical EOF string capability (underbar is taken literally). xargs reads the standard input until either EOF or the logical EOF string is encountered.

-ireplstr
    Insert mode: command is executed for each line from the standard input, taking the entire line as a single argument, inserting it in initial-arguments for each occurrence of replstr. A maximum of 5 arguments in initial-arguments may each contain one or more instances of replstr. SPACE and TAB characters at the beginning of each line are thrown away. Constructed arguments may not grow larger than 255 characters, and option -x is also forced. {} is assumed for replstr if not specified.

-lnumber
    command is executed for each nonempty number lines of arguments from the standard input. The last invocation of command will be with fewer lines of arguments if fewer than number remain. A line is considered to end with the first NEWLINE unless the last character of the line is a SPACE or a TAB; a trailing SPACE or TAB signals continuation through the next non-empty line. If number is omitted, 1 is assumed. The -x option is forced.

-nnumber
    Execute command using as many standard input arguments as possible, up to number arguments maximum. Fewer arguments will be used if their total size is greater than size characters, and for the last invocation if there are fewer than number arguments remaining. If option -x is also coded, each number arguments must fit in the size limitation, else xargs terminates execution.

-ssize
    The maximum total size of each argument list is set to size characters; size must be a positive integer less than or equal to 470. If -s is not coded, 470 is taken as the default. Note: the character count for size includes one extra character for each argument and the count of characters in the command name.

EXAMPLES

The following will move all files from directory $1 to directory $2, and echo each move command just before doing it:

    ls $1 | xargs -i -t mv $1/{} $2/{}

The following will combine the output of the parenthesized commands onto one line, which is then echoed to the end of file log:

    (logname; date; echo $0 $*) | xargs >>log

The user is asked which files in the current directory are to be archived and archives them into arch(1) one at a time, or many at a time.

    ls | xargs -p -l ar r arch
    ls | xargs -p -l | xargs ar r arch

The following will execute diff(1) with successive pairs of arguments originally typed as shell arguments:

    echo $* | xargs -n2 diff

SEE ALSO
arch(1), diff(1), sh(1)