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, /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
Copyright 1994 Novell, Inc. Page 1
xargs(1) xargs(1)
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
Copyright 1994 Novell, Inc. Page 2
xargs(1) xargs(1)
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.
Copyright 1994 Novell, Inc. Page 3
xargs(1) xargs(1)
-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.
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
Copyright 1994 Novell, Inc. Page 4
xargs(1) xargs(1)
/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.
Copyright 1994 Novell, Inc. Page 5