xargs(1) 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, /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 newlines; 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 (\) will
escape 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 option). Flag
options -i, -l, and -n determine how arguments are selected
for each command invocation. When none of these flag
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 no more arguments. When there are flag option
conflicts (e.g., -l vs. -n), the last flag option has
precedence. Flag option values 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
newline 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. Flag option
-x is forced.
-ireplstr Insert mode: command is executed for each line
from standard input, taking the entire line as a
single argument, inserting it in initial-
Page 1 (last mod. 1/16/87)
xargs(1) xargs(1)
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 flag 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 flag 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 at 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 flag options -i and -l. When none
of the flag 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).
Page 2 (last mod. 1/16/87)
xargs(1) xargs(1)
xargs reads standard input until either end-of-
file or the logical EOF string is encountered.
xargs will terminate if either:
it cannot execute command
command returns a -1 exit status.
When command is a shell program, it should explicitly exit
(see sh(1)) with an appropriate value to avoid accidentally
returning with -1.
EXAMPLE
ls $1 | xargs -i -t mv $1/{} $2/{}
will move all files from directory $1 to directory $2, and
echo each move command just before doing it.
(logname; date; echo $0 $*) | xargs >>log
will combine the output of the parenthesized commands onto
one line, which is then echoed to the end of file log.
ls | xargs -p -l ar r arch
ls | xargs -p -l | xargs ar r arch
causes the user to be asked which files in the current
directory are to be archived and archives them into arch one
at a time in the first instance, or as in the second
instance, many at a time.
echo $* | xargs -n2 diff
will execute diff(1) with successive pairs of arguments
originally typed as shell arguments.
FILES
/usr/bin/xargs
SEE ALSO
csh(1), ksh(1), sh(1).
DIAGNOSTICS
Self-explanatory.
Page 3 (last mod. 1/16/87)