xargs(1) xargs(1)
NAME
xargs - construct argument list(s) and execute command
SYNOPSIS
xargs [option ...] [command [initialargument ...]]
DESCRIPTION
xargs combines command-line arguments with arguments that it reads
from standard input and executes the specified command one or more
times. The number of arguments read for each command invocation and
the manner in which they are combined can be determined by the options
specified.
Arguments read in from standard input are defined to be contiguous
strings of characters delimited by one or more blanks, tabs, or new-
line characters; empty lines are discarded. Blanks and tabs may be
embedded as part of an argument only if they are either escaped with a
backslash \ or if the argument is enclosed in single or double quotes
('...' or "..."). Otherwise, they are interpreted as separators
between arguments. The usual quoting mechanisms apply as well, i.e.
metacharacters are also escaped as mentioned above.
OPTIONS
Options -i or -I, -l or -L and -n determine how the command-line argu-
ments and the arguments read from standard input are to be selected
for each invocation of command.
If none of the -I (or -i), -L (or -l), or -n options are used:
The initial arguments specified in the xargs command line are
followed by arguments read continuously from standard input until
an internal buffer is full. command is then executed with the
accumulated arguments. This process is repeated until there are
no more arguments.
If combinations of the -I (or -i), -l (or -l), or -n options are used:
When there are conflicts (e.g. -l and -n), the last specified
option takes effect.
-I repstr
Insert mode; command is executed for each line read from standard
input, taking each line as an argument and inserting it for each
occurrence of repstr in the list of initial arguments specified
when xargs was called.
A maximum of 5 arguments in the list of initial arguments may
each contain one or more instances of repstr. Blanks and tabs at
the beginning of each line are ignored. Constructed arguments may
not grow larger than 255 characters.
The -I option automatically also sets the -x option.
This corresponds to the old option -i, which is still supported.
Page 1 Reliant UNIX 5.44 Printed 11/98
xargs(1) xargs(1)
For repstr, braces {} are assumed in the case of -i if not expli-
citly specified.
-L number
command is executed for every number non-empty argument lines
that xargs reads from standard input. If fewer than number lines
remain when command is invoked for the last time, command will be
executed with these lines.
A line is considered to end with the first newline character in
it unless the last character in the line is a blank or a tab. A
trailing blank or tab signals continuation to the next non-empty
line.
This corresponds to the old option -l, which is still supported.
If number is not specified for -l, the value 1 is assumed. -x is
set automatically for -l.
-n number
Executes command using as many standard input arguments as possi-
ble (up to a maximum of number). Fewer arguments will be used if
their total size is greater than maxsize characters (see -s
option). If fewer than number arguments remain for the last invo-
cation, these arguments will be used. If option -x is also set,
each number arguments must not exceed the maximum limitation
specified with maxsize (see option -s), as otherwise xargs will
terminate execution.
-E eofstr
Defines eofstr as the logical end-of-file string. xargs reads
from standard input until either the actual end-of-file or the
logical eofstr is encountered.
Specify a string for eofstr. This string is interpreted as the
logical end-of-file string when xargs is executed.
This corresponds to the old option -e, which is still supported.
If -e is specified without eofstr, a logical end-of-file string
is no longer specified. The underscore _ has no special meaning
and is processed as a normal character.
Neither -E nor -e specified: The underscore _ is interpreted as
the logical end-of-file.
-p Prompt mode; the user is asked whether to execute command at each
invocation. In addition, the trace mode (option -t) is turned on
to print the invoked command, followed by a ?... prompt.
Page 2 Reliant UNIX 5.44 Printed 11/98
xargs(1) xargs(1)
-s maxsize
Sets the maximum number of characters in each argument list to
maxsize. An argument list is a combination of arguments formed on
the basis of rules defined by the -I (or -i), -L (or -l), or -n
options. Note that the character count for maxsize includes one
extra character for each argument and the count of characters in
the command name.
-t Trace mode; the command and each constructed argument list are
echoed to standard error just prior to their execution.
-x Causes xargs to terminate if any argument list would exceed the
specified maximum of maxsize characters (see option -s).
The -x option is forced when options -I (or -i) and -l are set.
When none of the -I (bzw. -i), -L (or -l), or -n options are
coded, the execution of xargs is terminated if the total length
of all arguments exceeds maxsize characters (see option s).
-- If command begins with a dash (-), the end of the command-line
options must be marked with --.
command
Any command may be specified for command. xargs will terminate if
it receives an exit status of 255 from command or cannot execute
it. If command is a shell script, it should include an exit com-
mand which explicitly returns a suitable exit status so as to
avoid accidentally returning with 255 (e.g. exit -1).
command not specified: The command echo is assumed for command.
initialargument
Argument lists are constructed (as described above) by combining
initial arguments specified on the xargs command line with argu-
ments read from the standard input (see options -I, -L, and -n).
The specified command is then executed with these argument lists.
The initial arguments always appear at the beginning of an argu-
ment list, except when the -I or -i option is set.
initialargument not specified: Argument lists are only con-
structed from arguments read from the standard input.
EXIT STATUS
0 Each call of command returned the exit status 0.
1-125 The arguments could not be combined as requested, or at least
one call of command returned a non-zero exit status or a further
error occurred.
126 The specified command exists, but cannot be executed.
Page 3 Reliant UNIX 5.44 Printed 11/98
xargs(1) xargs(1)
127 The specified command cannot be found.
LOCALE
The LCMESSAGES environment variable governs the language in which
message texts are displayed.
LCCOLLATE governs the collating sequence.
LCCTYPE governs character classes and character conversion (shift-
ing).
If LCMESSAGES, LCCOLLATE or LCCTYPE is undefined or is defined as
the null string, it defaults to the value of LANG. If LANG is likewise
undefined or null, the system acts as if it were not international-
ized.
The LCALL environment variable governs the entire locale. LCALL
takes precedence over all the other environment variables which affect
internationalization.
If any of the locale variables has an invalid value, the system acts
as if none of the variables were set.
EXAMPLES
Example 1
The following shell script named relocate moves files with names that
do not begin with a period (.) from one directory to another:
$ cat relocate
ls $1 | xargs -I {} -t mv $1/{} $2/{}
$ relocate dir1 dir2
mv dir1/file1 dir2/file1
mv dir1/file2 dir2/file2
mv dir1/file3 dir2/file3
The two positional parameters $1 and $2 are assigned the values of the
arguments specified (dir1 and dir2) when relocate is invoked. The com-
mand ls $1 displays the contents of the dir1 directory with one file
name in each line. These file names are sequentially inserted for {}
(option -I {}). Each mv command is echoed with its argument list
(option -t) just before it is invoked.
Example 2
The following shell script named whoandwhen collects the output of
the parenthesized commands (...) in one line and appends this line to
the end of the file log:
$ cat whoandwhen
(logname; date; echo $0 $*) | xargs >>log
Page 4 Reliant UNIX 5.44 Printed 11/98
xargs(1) xargs(1)
$ cat log
michael Wed Mar 29 14:21:06 MET 1989 whoandwhen
Example 3
The following shell script named archive places files in the current
directory whose names do not begin with a period (.) in an archive
named archive.a [see ar(1)]:
$ cat archive
ls | xargs -p -L 1 ar r archive.a
$ archive
ar r archive.a file1 ?... y
ar: creating archive.a
ar r archive.a file2 ?... n
ar r archive.a file3 ?... y
ar r archive.a file4 ?... n
$ ar t archive.a
file1
file3
ls displays the contents of the current directory on standard output
with one file name in each line. xargs then calls ar with the argu-
ments r, archive.a, and each file name returned by ls. Since the -p
option has been set, you are asked whether or not the corresponding ar
command is to be executed in each case. If you respond with a "y" the
first time, ar creates the archive file archive.a, issues a corre-
sponding message, and saves the current file in it. Your subsequent
responses to each prompt will then determine which files are to be
stored in archive.a. If required, the contents of archive.a can be
listed at the end with the ar t command.
SEE ALSO
echo(1).
Page 5 Reliant UNIX 5.44 Printed 11/98