xargs(1) General Commands Manual xargs(1)
Name
xargs - construct argument list and execute command
Syntax
xargs [flags] [ command [initial-arguments] ]
Description
The command combines fixed initial-arguments with arguments read from standard input to execute a specified command one or more times. The
number of arguments read when a command is invoked and how they are combined is determined by the options specified.
The specified command, (which can be a Shell file) is searched for using ones' $PATH specification. If command is not specified, /bin/echo
is used.
Arguments read from standard input are defined as contiguous strings of characters delimited by one or more blanks, tabs, or newlines;
empty lines are always discarded. Blanks and tabs can be embedded as part of an argument if they contain an escape character or if they
are quoted. Characters enclosed in quotes (single or double) are taken literally, and the delimiting quotes are removed; a backslash ()
escapes the next character.
Options
Each argument list begins with the initial-arguments, followed by arguments read from standard input, with the exception of the -i option.
See the description of the -i option for more information.
The options -i, -l, and -n determine how arguments are selected when each command is invoked. If none of these options are specified, the
initial-arguments are followed by arguments read continuously from standard input until the internal buffer is full; then, command executes
with the accumulated arguments. This process repeats until no arguments exist. When conflicts arise, such as the -l option used with the
-n, the last option has precedence. The options values are as follows:
-lnumber
Execute command for each non-empty number lines of arguments from standard input. When command is invoked for the final time, it has
fewer lines of arguments if fewer than a specified number remain. A line ends with the first newline 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 is not
specified, the value 1 is assumed. The option -x is forced.
-ireplstr (Insert mode)
Execute command for each line from standard input, taking the entire line as a single argument and inserting it in initial-arguments
for each occurrence of replstr. A maximum of five arguments specified in initial-arguments can contain one or more occurrence of
replstr. Blanks and tabs at the beginning of each line are discarded. A constructed arguments cannot exceed 255 characters and the
option -x is a forced. A {|} is assumed for replstr if not specified.
-nnumber
Execute command using as many standard input arguments as possible, up to the specified number arguments maximum. Fewer arguments
are used if their total size is greater than size characters, and when the last command is invoked, fewer number of arguments remain.
If the option -x is also include, each specified number of arguments must fit in the size limitation, or else xargs terminates execu-
tion.
-t (Trace mode)
Echo the command and each constructed argument list to file descriptor 2 prior to their execution.
-p (Prompt mode)
Asks the user whether or not command should be executed each time command is invoked. Trace mode (-t) is turned on to print the com-
mand instance to be executed, followed by a ?... prompt. A reply of y executes the command; any other response does not invoke that
particular command.
-x Causes the command xargs to terminate if an argument list is greater than the specified size of characters; the option -x is forced
by the options -i and -l. When the options -i, -l, or -n are included, the total length of all arguments must be within the speci-
fied size limit.
-ssize
The maximum 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 included, 470 is 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
The option eofstr is taken as the logical end-of-file string. Underscore (_) is assumed for the logical EOF string if -e is not
specified. The value -e without eofstr specified turns off the logical EOF string capability; the underscore is taken literally.
The command xargs reads standard input until either end-of-file or the logical EOF string is encountered.
The command xargs terminates if it receives a return code of -1 from command or if it cannot execute command. When command is a Shell pro-
gram, it should explicitly exit with an appropriate value to avoid returning with -1. See for more information.
Examples
The following example moves all files from directory $1 to directory $2 and echoes the move command prior to executing 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
In the next example, the user is prompted to specify which files in the current directory are to be archived. The first example archives
the files one at a time; the second example archives groups of files:
ls | xargs -p -l ar r arch
ls | xargs -p -l | xargs ar r arch
The following example executes diff(1) with successive pairs of arguments originally typed as Shell arguments:
echo $* | xargs -n2 diff
See Also
sh(1).
xargs(1)