XARGS(C) UNIX System V
Name
xargs - constructs and executes commands
Syntax
xargs [flags] [ command [initial-arguments] ]
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 flags specified.
Command, which may be a shell file, is searched for using
the shell $PATH variable. 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). 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 command is executed with the accumulated args.
This process is repeated until there are no more args. When
there are flag conflicts (e.g., -l vs. -n), the last flag
has precedence. Flag values are:
-lnumber Command is executed for each number lines of
nonempty arguments from the standard input.
This is instead of the default single line of
input for each command. 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 nonempty line. If number is omitted, 1
is assumed. Option -x is forced.
-ireplstr Insert mode: command is executed for each line
from the 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 Executes command , using as many standard input
arguments as possible, up to the number of
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 of
arguments must fit in the size limitation, or
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 prompted whether to
execute command at each invocation. Trace mode
(-t) is turned on to display 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 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. Underscore (_) is assumed for the
logical EOF string if -e is not coded. -e with
no eofstr coded turns off the logical EOF string
capability (underscore is taken literally).
xargs reads standard input until either end-of-
file or the logical EOF string is encountered.
xargs terminates if it either 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(C)) with an
appropriate value to avoid accidentally returning with -1.
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 prompted to enter which files in the current
directory are to be printed and prints them one at a time:
ls | xargs -p -l lpr
Or many at a time:
ls | xargs -p -l | xargs lpr
The following will execute diff(C) with successive pairs of
arguments originally entered as shell arguments:
echo $* | xargs -n2 diff
Standards Conformance
xargs is conformant with:
AT&T SVID Issue 2, Select Code 307-127;
and The X/Open Portability Guide II of January 1987.
(printed 2/15/90) XARGS(C)