xargs
PURPOSE
Constructs argument lists and runs commands.
SYNOPSIS
xargs [flags] [ command [initial-arguments] ]
DESCRIPTION
The xargs command runs a command line. It constructs the
command line by combining cmdstring, a string containing
a command and its flags or parameters, with additional
arguments read from standard input. It runs cmdstring as
many times as necessary to process all input arguments.
The default cmdstring is echo.
Arguments read from standard input are character strings
delimited by one or more blanks, tabs, or new-line char-
acters. You can embed a blank or a tab in arguments by
preceding it with a \ (backslash) or by quoting it.
xargs reads characters enclosed in single or double
quotes as literals and removes the delimiting quotes. It
always discards empty lines.
FLAGS
-e[eofstr] Sets the logical end-of-file string to
eofstr. xargs reads standard input until it
encounters either an end-of-file character
or the logical EOF string. If you do not
specify the -e flag, the default eofstr is _
(the underline character). If you specify
-e with no eofstr, xargs interprets the
underline character as a literal character
rather than as an end-of-file marker.
-i[replstr] Takes an entire line as a single argument
and inserts it in each instance of replstr
found in cmdstring. A maximum of five argu-
ments in cmdstring may each contain one or
more instances of replstr. xargs discards
blanks and tabs at the beginning of each
line. The argument constructed may not be
larger than 255 characters. The default
replstr is "{}". This flag also turns on
the -x flag.
-l[num] Runs cmdstring with the specified num of
nonempty argument lines read from standard
input. The last invocation of cmdstring can
have fewer argument lines if fewer than num
remain. A line ends with the first new-line
character unless the last character of the
line is a blank or a tab. A trailing blank
or tab indicates a continuation through the
next nonempty line. The default num is 1.
This flag turns on the -x flag.
-nnum Executes cmdstring using as many standard
input arguments as possible, up to a maximum
of num. xargs uses fewer arguments if their
total size is greater than the number of
characters specified by the -ssize flag
described following. It also uses fewer
arguments for the last invocation if fewer
than num arguments remain. When -x is
present, each num argument must fit the size
limitation specified by -x.
-p Asks whether or not to run cmdstring. It
displays the constructed command line, fol-
lowed by a "?" . . . prompt. Press "y" to
run the cmdstring. Any other response
causes xargs to skip that particular invoca-
tion of cmdstring. You are asked about each
invocation.
-ssize Sets the maximum total size of each argument
list. size must be a positive integer less
than or equal to 470. The default size is
470 characters. Note that the character
count for size includes one extra character
for each argument and the number of charac-
ters in the command name.
-t Echoes the cmdstring and each constructed
argument list to file descriptor 2 (usually
standard error).
-x Stops running xargs if any argument list is
greater than the number of characters speci-
fied by the -ssize. This flag is turned on
if you specify either the -i or -l flags.
If you do not specify -i, -l, or -n, the
total length of all arguments must be within
the size limit.
Note: The xargs command ends if it cannot run cmdstring
or if it receives a return code of -1. When cmdstring
calls a shell procedure, the shell procedure should
explicitly exit with an appropriate value to avoid acci-
dentally returning -1. (See "sh.")
EXAMPLES
1. To use a command on files whose names are listed in a
file:
xargs lint -a <cfiles1 *
If "cfiles" contains the text:
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 characters
long. If "cfiles" contains more file names than fit
on a single line, then xargs runs the lint command
with the file names that fit. It then constructs and
runs another lint command using the remaining file
names. Depending on the names listed in "cfiles",
the commands might look like:
lint -a main.c readit.c gettoken.c . . .
lint -a getisx.c getprp.c getpid.c . . .
lint -a fltadd.c fltmult.c fltdiv.c . . .
This is not quite the same as running lint once with
all the file names. 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 command
lines.
For this reason you may want to run the command only
if all the file names fit on one line. Tell xargs
this by using the -x flag:
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.
2. To construct commands that contain a certain number
of file names:
xargs -t -n2 diff <<end
starting chap1 concepts chap2 writing
chap3
end
This constructs and runs diff commands that contain
two file names each (-n"2"):
diff starting chap1
diff concepts chap2
diff writing chap3
The -t flag tells xargs to display each command
before running it so that you can see what is hap-
pening. The "<<end" and "end" define a "Here Docu-
ment," which uses the text entered before the "end"
line as standard input for the xargs command. For
more details, see "Inline Input Documents."
3. To insert file names into the middle of commands:
ls | xargs -t -i mv {} {}.old
This renames all files in the current directory by
adding ".old" to the end of each name. The -i tells
xargs to insert each line of the ls directory listing
where a "{}" appears. If the current directory con-
tains the files "chap1", "chap2", and "chap3", then
this constructs the commands:
mv chap1 chap1.old
mv chap2 chap2.old
mv chap3 chap3.old
4. To run a command on files that you select individ-
ually:
ls | xargs -p -n1 ar r lib.a
This allows you to select files to add to the library
"lib.a". The -p flag tells xargs to display each ar
command it constructs and ask if you want to run it.
Type y and press Enter to run the command. Press
Enter alone if you do not want to run it.
RELATED INFORMATION
The following command: "sh."