xargs(1)xargs(1)NAMExargs - Constructs argument lists and runs commands
SYNOPSISxargs [-e[eofstr]] [-E eofstr] [-i[replstr]] [-I replstr] [-l[number]]
[-L number] [-n[number]] [-ptrx] [-slength] [CommandString] [argu‐
ment...]
The xargs command constructs a command line by combining a command
string, containing a command and its options or arguments, with addi‐
tional arguments read from standard input.
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
xargs: XCU5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
OPTIONS
Sets the logical end-of-file string to eofstr. The xargs command reads
standard input until it encounters either an end-of-file character or
the logical end-of-file string. If you do (underline). If you specify
-e with no eofstr, xargs interprets the underline character as a lit‐
eral character, rather than as an end-of-file marker. Specifies a log‐
ical end-of-file string to replace the default underscore. The xargs
command reads standard input until either an end-of-file character or
the logical end-of-file string is encountered. Takes an entire line as
a single argument and inserts it in each instance of replstr found in
the command string. A maximum of five arguments in the command string
can each contain one or more instances of replstr. The xargs command
discards spaces and tabs at the beginning of each line. The argument
constructed cannot be larger than 255 bytes. The default replstr is
{}. This option also turns on the -x option. Insert mode: command is
executed for each line from standard input, taking the entire line as a
single argument, inserting it in arguments for each occurrence of
replstr. Any blank characters at the beginning of each line are
ignored. Constructed arguments cannot grow larger than 255 bytes.
Option -x is forced on. The -I and -i options are mutually exclusive;
the last one specified takes effect. Runs the command string with the
specified number of nonempty argument lines read from standard input.
The last invocation of the command string can have fewer argument lines
if fewer than number remain. A line ends with the first newline char‐
acter unless the last character of the line is a space or a tab. A
trailing space or tab indicates a continuation through the next
nonempty line. The default number is 1. This option turns on the -x
option. The command is executed for each non-empty number lines of
argument from standard input. The last invocation of command has fewer
lines of argument if fewer than number remain. A line is considered to
end with the first newline character unless the last character of the
line is a blank character. A trailing blank character signals continua‐
tion to the next non-empty line, inclusive. The -L, -l and -n options
are mutually exclusive; the last one takes effect. Executes the com‐
mand string using as many standard input arguments as possible, up to a
maximum of number. The xargs command uses fewer arguments if their
total length is greater than the number of characters specified by the
-s [length] option. It also uses fewer arguments for the last invoca‐
tion if fewer than number arguments remain. When -x is present, each
number argument must fit the length limitation specified by -s. Asks
whether or not to run the command string. It displays the constructed
command line, followed by a ?... prompt. Press y, or the locale's
equivalent of a y, to run the command string. Any other response
causes xargs to skip that particular invocation of the command string.
You are asked about each invocation. Sets the maximum total length of
each argument list. The length must be a positive integer less than or
equal to 470. The default length is 470 bytes. Note that the charac‐
ter count for length includes one extra character for each argument and
the number of characters in the command name. Echoes the command
string and each constructed argument list to file descriptor 2 (usually
standard error). Stops running xargs if any argument list is greater
than the number of characters specified by the -s length option. This
option is turned on if you specify either the -i or -l options. If you
do not specify -i, -l, or -n, the total length of all arguments must be
within the length limit.
OPERANDS
The name of the command to be invoked, found by searching the path
using the PATH environment variable. If CommandString is omitted, the
default is the echo command. An initial option or operand for the
invocation of CommandString.
DESCRIPTION
The xargs command runs the command string as many times as necessary to
process all input arguments. The default command string is echo.
Arguments read from standard input are character strings delimited by
one or more spaces, tabs, or newline characters. You can embed a space
or a tab in arguments by preceding it with a \ (backslash) or by quot‐
ing it. The xargs command reads characters enclosed in single or dou‐
ble quotes as literals and removes the delimiting quotes. It always
discards empty lines.
The xargs command ends if it cannot run the command string or if it
receives an exit code of -1. When the command string calls a shell
procedure, the shell procedure should explicitly exit with an appropri‐
ate value to avoid accidentally returning -1. (See the sh command.)
The LC_MESSAGES variables determines the locale's equivalent of y and n
(for yes/no queries).
EXIT STATUS
The following exit values are returned: All invocations of Command‐
String returned exit status zero. A command line meeting the specified
requirements could not be assembled, one or more of the invocations of
CommandString returned a non-zero exit status, or some other error
occurred. The command specified by CommandString was found but could
not be invoked. The command specified by CommandString could not be
found.
EXAMPLES
To use a command on files whose names are listed in a file, use a com‐
mand line similar to the following: xargs lint -a < cfiles
If cfiles contains the text, enter: main.c readit.c gettoken.c
putobj.c
then xargs constructs and runs the command: lint -a main.c
readit.c gettoken.c putobj.c
Each shell command line can be up to 470 bytes long. If cfiles
contains more file namess than fit on a single line, then xargs
runs the lint command with the file namess that fit. It then
constructs and runs another lint command using the remaining
file namess. Depending on the names listed in cfiles, the com‐
mands might look like the following:
lint -a main.c readit.c gettoken.c... lint -a getisx.c
getprp.c getpid.c... lint -a fltadd.c fltmult.c flt‐
div.c...
This is not quite the same as running lint once with all the
file namess. The lint command checks cross-references between
files. However, in this example it cannot check between main.c
and fltadd.c, or between any two files listed on separate com‐
mand lines.
For this reason you might want to run the command only if all
the file namess fit on one line. Do this by using xargs with the
-x option: xargs-x lint -a <cfiles
If all the file names in cfiles do not fit on one command line,
then xargs displays an error message. To construct commands
that contain a certain number of file namess, use a command line
similar to the following: xargs-t-n2 diff <<end starting
chap1 concepts chap2 writing chap3 end
This constructs and runs diff commands that contain two file
names each (-n2):
diff starting chap1 diff concepts chap2 diff writing chap3
The -t option tells xargs to display each command before running
it so that you can see what is happening. The <<end and end
arguments define a Here Document, which uses the text entered
before the end line as standard input for the xargs command.
(For more details, see the section Inline Input (Here) Documents
in the sh(1) reference page.) To insert file namess into the
middle of commands, use a command line similar to the following:
ls | xargs-t -i mv {} {}.old
This renames all files in the current directory by adding to the
end of each name. The -i tells xargs to insert each line of the
ls directory listing where { } (braces) appear. If the current
directory contains the files chap1, chap2, and chap3, then this
constructs the following commands:
mv chap1 chap1.old mv chap2 chap2.old mv chap3 chap3.old
To run a command on files that you select individually, use a
command line similar to the following: ls | xargs-p-n1 ar
r lib.a
This allows you to select files to add to the library lib.a.
The -p option tells xargs to display each ar command it con‐
structs and ask if you want to run it. Press y, or the locale's
equivalent of a y, and press <Return> to run the command. Press
<Return> alone if you do not want to run it.
ENVIRONMENT VARIABLES
The following environment variables affect the execution of xargs: Pro‐
vides a default value for the internationalization variables that are
unset or null. If LANG is unset or null, the corresponding value from
the default locale is used. If any of the internationalization vari‐
ables contain an invalid setting, the utility behaves as if none of the
variables had been defined. If set to a non-empty string value, over‐
rides the values of all the other internationalization variables.
Determines the locale for the interpretation of sequences of bytes of
text data as characters (for example, single-byte as opposed to multi‐
byte characters in arguments and input files) and the behavior of char‐
acter classes used for yesexprlocal keyword in the LC_MESSAGES cate‐
gory. Determines the locale for the format and contents of diagnostic
messages written to standard error. Determines the location of message
catalogues for the processing of LC_MESSAGES. Determines the location
of CommandString.
SEE ALSO
Commands: ksh(1), Bourne shell sh(1b), POSIX shell sh(1p)
Standards: standards(5)xargs(1)