xargs(1) UNIX System V(User Environment Utilities) xargs(1)
NAME
xargs - construct argument list(s) and execute command
SYNOPSIS
xargs [ flags ] [ command [ initial-arguments ] ]
DESCRIPTION
xargs 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 flags 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 standard input are defined to be contiguous
strings of characters delimited by one or more blanks, tabs, or new-
lines; empty lines are always discarded. Blanks and tabs may be embedded
as part of an argument if 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 (\) escapes the next
character.
Each argument list is constructed starting with the initial-arguments,
followed by some number of arguments read from standard input (Exception:
see -i flag). Flags -i, -l, and -n determine how arguments are selected
for each command invocation. When none of these flags 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 args. This process is repeated until there
are no more args. When there are flag conflicts (for example, -l vs.
-n), the last flag has precedence. Valid flags are:
-lnumber command is executed for each non-empty 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 five 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.
10/89 Page 1
xargs(1) UNIX System V(User Environment Utilities) xargs(1)
-nnumber Execute command using as many standard input arguments as
possible, up to number arguments maximum. Fewer arguments
are 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)
executes 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.
xargs terminates if either it receives a return code of -1 from, or if it
cannot execute, command. When command is a shell program, it should
explicitly exit (see sh(1)) with an appropriate value to avoid
accidentally returning with -1.
EXAMPLES
The following examples moves 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/{}
Page 2 10/89
xargs(1) UNIX System V(User Environment Utilities) xargs(1)
The following example combines 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 example executes diff(1) with successive pairs of arguments
originally typed as shell arguments:
echo $* | xargs -n2 diff
SEE ALSO
sh(1)
10/89 Page 3