xargs(1)
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
and
-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 or tab signals continuation through the next non-empty line.
If
number
is omitted, 1 is assumed.
Option
-x
is forced.
The -L option is preferred; it is the same as the -l option
except that it requires an option argument.
-L number-
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 or tab signals continuation through the next non-empty line.
If
number
is omitted, 1 is assumed.
Option
-x
is forced.
This option is the same as the -l option except that an
option argument is required for compliance with XPG4.
-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.
The -I option is preferred; it is the same as the -i option
except that it requires an option argument.
-I replstr-
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.
This option is the same as the -i option except that an
option argument is required for compliance with XPG4.
-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 locale-specific affirmative response
executes the command; anything else, including
a <Return>, skips that particular invocation of
command.
In the C locale,
an affirmative response
is a line that starts with an uppercase
or lowercase y.
-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 {ARG_MAX}-2048.
If
-s
is not coded, {ARG_MAX}-2048 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.
The -E option is preferred; it is the same as the -e option
except that it requires an option argument.
-E eofstr-
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.
This option is the same as the -e option except that an
option argument is required for compliance with XPG4.
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.
The xargs command terminates with exit code 127 if the utility
specified on the command line could not be found; exit code 126 is
returned if the utility could be found but not executed.
Examples
The following example 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/{}
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 command-line arguments:
echo $ | xargs -n2 diff
This last example assumes there are no embedded spaces
in the elements of the orignal argument list.
Files
/usr/lib/locale/locale/LC_MESSAGES/uxcore-
language-specific message file
(See LANG in
environ(5).)
References
sh(1)
Notices
xargs may never be able to invoke a utility if the environment passed
in to xargs comes close to using ARG_MAX}-2048 bytes.
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004