XARGS(1,C) AIX Commands Reference XARGS(1,C)
-------------------------------------------------------------------------------
xargs
PURPOSE
Constructs argument lists and runs commands.
SYNTAX
+--------+ +------------------+ +-- -s470 --+ +------+
xargs ---| one of |---+-- -nnum ---------+---| |---| |--->
| +----+ | | +---1---+ | +- -ssize --+ +- -x -+
+-| -p |-+ +-- -l --| |-+
| -t | +- num -+
+----+
+----- -e -------+ +-----------------+ +--- echo ----+
>---| +---- -e ----+ |---| +---- -i -----+ |---| |---|
+-| |-+ +-| |-+ +- cmdstring -+
+- -eeofstr -+ +- -ireplstr -+
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 characters. You can imbed a blank or a tab in
arguments by preceding it with a \ (backslash) or by quoting it. The xargs
command 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. The xargs command
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
arguments in cmdstring may each contain one or more instances of
Processed November 8, 1990 XARGS(1,C) 1
XARGS(1,C) AIX Commands Reference XARGS(1,C)
replstr. The xargs command 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 non-empty 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 non-empty 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 below. 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 to run cmdstring. It displays the constructed
command line, followed by a "?"... prompt. Press "y" to run the
cmdstring. Any other response causes xargs to skip that
particular invocation 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. The character count for size includes one
extra character for each argument and the number of characters 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 specified 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.
Notes:
1. If you have selected a language (through the LANG environment variable)
that supports multibyte characters, the character limits cited in the -i
and -s descriptions can be reduced by as much as 50%, depending on the
character code set being used.
2. 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
Processed November 8, 1990 XARGS(1,C) 2
XARGS(1,C) AIX Commands Reference XARGS(1,C)
procedure should explicitly exit with an appropriate value to avoid
accidentally returning -1. (See "sh, Rsh.")
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, 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, 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"):
Processed November 8, 1990 XARGS(1,C) 3
XARGS(1,C) AIX Commands Reference XARGS(1,C)
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 happening. The "<<end" and "end" define a "Here
Document," 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 contains 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 individually:
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
See the following command: "sh, Rsh."
Processed November 8, 1990 XARGS(1,C) 4