Format
xargs [–I placeholder]
[–i [placeholder]]
[–L number] [–l [number]]
[–n number] [–ptx]
[–E [eofstr]]
[–e [eofstr]]
[–s size] [command [argument
…]]
Description
The xargs command
line typically contains the
skeleton, or template, of another command. This template looks like a normal command, except
that it lacks some arguments. xargs adds
arguments from standard input (the standard input) to complete the
command, then runs the resulting command. If more input remains, it
repeats this process.
In a double-byte locale, some options
may accept a double-byte string as an argument. In these cases, an
incorrect double-byte string would be detected during command-line
parsing.
Restriction: The maximum length of a constructed
command is LINE_MAX bytes.
Options
xargs gets
the needed arguments from standard input (the standard input). Different
options tell how the standard input is to be interpreted to obtain
these arguments.
- –I placeholder
- Specifies that each line in the standard input (the standard input)
is to be considered as a single argument. The placeholder following
the –I is a string that can appear multiple
times in the command template. xargs strips
the input line of any leading white space characters and inserts it
in place of the placeholder string. For
example, with:
xargs –I '{}' mv dir1/'{}' dir2/ '{}'
The
standard input should consist of lines giving names of files that
you want moved from dir1 to dir2. xargs substitutes
these names for the {} placeholder in each place
that it appears in the command template.
When
xargs creates
arguments for the template command, no single argument can be longer
than 255 characters after the input has replaced the placeholders.
The
–x option
is automatically in effect
if –I or –i is
used. If you omit the placeholder string,
it defaults to the string { }. Thus we could write
our preceding example as: xargs –i mv dir1/ '{}' dir2/ '{}'
In
a double-byte locale, placeholder may contain
double-byte characters.
- –i placeholder
- Behaves like –I, except that the placeholder is
optional. If you omit the placeholder string,
it defaults to the string { }. Thus, the previous example could be
written as:
xargs –i mv dir1/ '{{ ' dir2/'{ } '
xargs –i /{}/ mv dir1/ '{}' dir2/ '{}
- –L number
- Specifies that xargs read number lines
from the standard input and concatenate them into one long string
(with a blank separating each of the original lines). xargs then
appends this string to the command template and runs the resulting
command. This process is repeated until xargs reaches
the end of the standard input if there are fewer than number lines
left in the file the last time the command is run, xargs just
uses what is there.
With this option, a line must contain at least
one nonblank character; blank lines are skipped and do not count toward
the number of lines being added to the template. xargs considers
a line to end at the first newline character, unless the last character
of the line is a blank or a tab; in this case, the current line is
considered to extend to the end of the next non-empty line.
If
you omit the –L or –l option,
the default number of lines read from the standard input is 1.
The –x option is automatically in effect
if –l is used.
- –l number
- Acts like the –L option, but the number argument
is optional. number defaults to 1.
- –n number
- Specifies xargs is to read the given
number of arguments from the standard input and put them on the end
of the command template. For example:
xargs –n 2 diff
obtains
two arguments from the standard input, appends them to the diff command,
and then runs the command. It repeats this process until the standard
input runs out of arguments. When you use this option, xargs considers
arguments to be strings of characters separated from each other by
white space characters (blanks, horizontal tabs, or newlines). Empty
lines are always skipped (that is, they don't count as arguments).
If you want an input argument to contain blanks or horizontal tabs,
enclose it in double quotes or single quotes. If the argument contains
a double-quote character ("), you must enclose the
argument in single quotes. Conversely, if the argument contains a
single quote (') (or an apostrophe), you must enclose
the argument in double quotes. You can also put a backslash (\)
in front of a character to tell xargs to
ignore any special meaning the character may have (for example, white
space characters, or quotes).
xargs reads
fewer than
number arguments if:
- The accumulated command line length exceeds the size specified
by the –s option (or {LINE_MAX} if
you did not specify –s)
- The last iteration has more than zero, but less than number arguments
remaining
If you do not specify the –n option,
the default number of arguments read from the standard input is 1.
Typically, an
xargs command
uses exactly one of the options just described. If you specify more
than one,
xargs uses the one that appears
last on the command line. If the command has none of these options,
xargs keeps
reading input until it fills up its internal buffer, concatenating
arguments to the end of the command template. When the buffer is full,
xargs runs
the resulting command, and then starts constructing a new command.
For example:
ls | xargs echo
prints the
names of files in the working directory as one long line. When you
invoke
xargs this way, the total length
of all arguments must be less than the size specified by the
–s option.
If
no command template appears on the command line, xargs uses echo by
default. When xargs runs a command, it uses
your search rules to find the command; this means that you can run
shell scripts as well as normal programs.
The command you want
to execute should be in your search $PATH.
xargs ends
prematurely if it cannot run a constructed command or if an executed
command returns a nonzero status.
If an executed command is
a shell program, it should explicitly contain an exit command
to avoid returning a nonzero by accident; see sh for
details.
You can use the following options with any of the
three main options.
- –E [eofstr]
- Defines eofstr to represent end-of-file
on the standard input. For example:
–E :::
tells xargs that ::: represents
the end of the standard input, even if an input file continues afterward.
If there is no –E or –e option,
a single underscore (_) marks the end of the input.
In a double-byte locale, eofstr may
contain double-byte characters.
- –e [eofstr]
- Acts like –E but the eofstr argument
is optional. If you specify –e without eofstr,
there is no end-of-file marker string, and _ is taken literally instead
of as an end-of-file marker. xargs stops
reading input when it reaches the specified end-of-file marker or
the true end of the file.
- –p
- Prompts you before each command. This option turns on the –t option
so that you see each constructed command before it is run. Then xargs displays ?…,
asking if you really want to run this command. If you type a string
beginning with y, xargs runs
the command as displayed; otherwise, the command is not run, and xargs constructs
a new command.
- –s size
- Sets the maximum allowable size of an argument list to size bytes
(where size is an integer). The value of size must
be less than or equal to the system variable LINE_MAX. If you omit
the –s option, the default allowable size
of an argument list is LINE_MAX. The length of the argument list is
the length of the entire constructed command; this includes the length
of the command name, the length of each argument, plus one blank for
separating each item on the line.
- –t
- Writes each constructed command to stderr just before running
the command.
- –x
- Kills xargs if it creates
a command that is longer than the size given by the –s option
(or {LINE_MAX} is –s was not specified).
This option comes into effect automatically if you specify –i or –l.
Examples
The following displays file names
in three columns:
ls | xargs –n 3 echo
Localization
xargs uses
the following localization environment variables:
- LANG
- LC_ALL
- LC_CTYPE
- LC_MESSAGES
- LC_SYNTAX
- NLSPATH
See Localization for more
information.
Exit values
- 0
- Successful completion of all commands
- 1–125
- Failure due to any of the following:
- xargs could not assemble a command line
- One or more invocations of command returned
a nonzero exit status.
- Some other error occurred
- 126
- xargs found command but
could not invoke it
- 127
- xargs could not find command
Portability
POSIX.2, X/Open Portability Guide, UNIX systems.
The –e, –E, –i, –I, –l, –L,
and –p options are extensions of the POSIX
standard.
Related information
echo, find, sh