XARGS(1)XARGS(1)NAMExargs - construct argument list(s) and execute command
SYNOPSISxargs [ -lnumber ] [ -ireplstr ] [ -nnumber ] [ -t ] [ -p ] [ -x ] [
-ssize ] [ -eeofstr ] [ command [initial-arguments] ]
DESCRIPTIONxargs combines the fixed initial-arguments with arguments read from
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, /bin/echo is used.
Arguments read in from 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 standard input
(Exception: see -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 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
(e.g., -l vs. -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-lnumber command is executed for each nonempty number lines of
arguments from 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
new-line unless the last character of the line is a blank or
a tab; a trailing blank/tab signals continuation through the
next non-empty line. If number is omitted, 1 is assumed.
Option -x is forced.
-ireplstr Insert mode: command is executed for each line from standard
input, taking the entire line as a single arg, 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. Blanks and tabs 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.
-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.
-t Trace mode: The command and each constructed argument list
are echoed to file descriptor 2 just prior to their
execution.
-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 carriage return,
skips that particular invocation of command.
-x Causes xargs to terminate 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.
-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 that the character count for size includes one
extra character for each argument and the count of characters
in the command name.
-eeofstr eofstr is taken as the logical end-of-file 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
standard input until either end-of-file or the logical EOF
string is encountered.
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 (2.) many
at a time.
1. ls | xargs-p -l ar r arch
2. 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 ALSOsh(1)
6 June 1986 XARGS(1)