Commands Reference, Volume 6

xargs Command

Purpose

Constructs parameter lists and runs commands.

Syntax

xargs [ -p ] [ -t ] [ -e [ EOFString ] ] [ -E EOFString ] [ -i [ ReplaceString ] ] [ -I ReplaceString ] [ -l [ Number ] ] [ -L Number ] [ -n Number [ -x ] ] [ -s Size ] [ Command [ Argument ... ] ]

Note: Do not put a blank space between the lowercase flags and the parameter.

Description

The generated command line length is the sum of the size, in bytes, of the Command and each Argument treated as strings, including a null byte terminator for each of these strings. The xargs command limits the command line length. When the constructed command line runs, the combined Argument and environment lists can not exceed ARG_MAX bytes. Within this constraint, if you do not specify the -n or the -s flags, the default command line length is at least the value specified by LINE_MAX.

Flags

-e[EOFString]	Obsolete flag. Use the -E flag. Uses the EOFString parameter as the logical EOF string. If you do not specify the -e or the -E flags, underscore (_) is assumed for the logical EOF string. If you do not specify the EOFString parameter, the logical EOF string capability is disabled, and underscores are taken literally. The xargs command reads from standard input until either EOF or the specified string is reached.
-E EOFString	Specifies a logical EOF string to replace the default underscore(_ ). The xargs command reads standard input until either EOF or the specified string is reached.
-i[ReplaceString]	Obsolete flag. Use the -I (Uppercase i) flag. If you do not specify the ReplaceString parameter, the string "{}" is used. Note: The -I (Uppercase i), and the -i flags are mutually exclusive; the last flag specified takes effect.
-I ReplaceString	(Uppercase i). Inserts each line of standard input as an argument for the Command parameter, inserting it in Argument for each occurrence of ReplaceString. ReplaceStrings can not be used in more than 5 arguments. Blank characters at the beginning of each standard input line are ignored. Each Argument can contain one or more ReplaceStrings, but may not be larger than 255 bytes. The -I flag also turns on the -x flag. Note: The -I (Uppercase i), and the -i flags are mutually exclusive; the last flag specified takes effect.
-l[Number]	(Lowercase L). Obsolete flag. Use the -L flag. If you do not specify the Number parameter, a value of 1 is used. The -l flag also turns on the -x flag. Note: The -L, -I (Lowercase L), and -n flags are mutually exclusive; the last flag specified takes effect.
-L Number	Runs the Command parameter with the specified number of nonempty parameter lines read from standard input. The last invocation of the Command parameter can have fewer parameter lines if fewer than the specified Number remain. A line ends with the first new-line character unless the last character of the line is a space or a tab. A trailing space indicates a continuation through the next nonempty line. Note: The -L, -I (Lowercase L), and -n flags are mutually exclusive; the last flag specified takes effect.
-n Number	Runs the Command parameter using as many standard input arguments as possible, up to the maximum specified by the Number parameter. The xargs command uses fewer arguments if: If the accumulated command line length exceeds the bytes specified by the -s Size flag. The last iteration has fewer than Number, but not zero, arguments remaining. Note: The -L, -I (Lowercase L), and -n flags are mutually exclusive; the last flag specified takes effect.
-p	Asks whether to run the Command parameter. It displays the constructed command line, followed by a `?...` (question mark, ellipsis) prompt. Enter an affirmative response specific to the locale to run the Command parameter. Any other response causes the xargs command to skip that particular invocation of the parameter. You are asked about each invocation. The -p flag also turns on the -t flag.
-s Size	Sets the maximum total size of the constructed Command line. The Size parameter must be a positive integer. Fewer arguments are used if: The total number of arguments exceeds those specified by the -n flag. The total number of lines exceeds those specified by the -L or -I (Lowercase L) flags. EOF is reached before the number of bytes specified by the Size parameter are accumulated.
-t	Enables the trace mode and echoes the constructed Command line to standard error before running.
-x	Stops running the xargs command if any Command line is greater than the number of bytes specified by the -s Size flag. This -x flag is turned on if you specify either the -I (Uppercase i) or -l (Lowercase L) flag. If you do not specify the -i, -I (Uppercase i), -l (Lowercase L), -L, or-n flag, the total length of the Command line must be within the limit specified by the -s Size flag.

Exit Status

This command returns the following exit values:

0	All invocations of the Command parameter returned exit status 0.
1-125	A command line meeting the specified requirements could not be assembled, one or more of the invocations of the Command parameter returned a non-zero exit status, or some other error occurred.
126	Command was found but could not be invoked.
127	Command could not be found.

If a command line meeting the specified requirements cannot be assembled, the command cannot be invoked, an invocation of the command is terminated by a signal, or an invocation of the command exits with exit status 255. The xargs command will write a diagnostic message and exit without processing any remaining input.

Examples

To use a command on files whose names are listed in a file, type:
```
xargs lint -a <cfiles
```
If the cfiles file contains the following text:
```
main.c readit.c
gettoken.c
putobj.c
```
the xargs command constructs and runs the following command:
```
lint -a main.c readit.c gettoken.c putobj.c
```
If the cfiles file contains more file names than fit on a single shell command line (up to LINE_MAX), the xargs command 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 the cfiles file, the commands 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 fltdiv.c . . .
```
This command sequence is not quite the same as running the lint command once with all the file names. The lint command checks cross-references between files. However, in this example, it cannot check between the main.c and the fltadd.c files, 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. To specify this to the xargs command use the -x flag by typing:

xargs -x lint -a <cfiles
If all the file names in the cfiles file do not fit on one command line, the xargs command displays an error message.
To construct commands that contain a certain number of file names, type:
xargs -t -n 2 diff <<EOF starting chap1 concepts chap2 writing chap3 EOF
This command sequence 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 causes the xargs command to display each command before running it, so you can see what is happening. The <<EOF and EOF pattern-matching characters define a here document, which uses the text entered before the end line as standard input for the xargs command.
To insert file names into the middle of command lines, type:
ls | xargs -t -I {} mv {} {}.old
This command sequence renames all files in the current directory by adding .old to the end of each name. The -I flag tells the xargs command to insert each line of the ls directory listing where {} (braces) appear. If the current directory contains the files chap1, chap2, and chap3, 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, type:
ls | xargs -p -n 1 ar r lib.a
This command sequence allows you to select files to add to the lib.a library. The -p flag tells the xargs command to display each ar command it constructs and to ask if you want to run it. Type y to run the command. Press the any other key if you do not want to run the command.
Something similar to the following displays:
```
ar r lib.a chap1 ?...
ar r lib.a chap2 ?...
ar r lib.a chap3 ?... 
```
To construct a command that contains a specific number of arguments and to insert those arguments into the middle of a command line, type:
```
ls | xargs -n6 | xargs -I{} echo {} - some files in the directory
```
If the current directory contains files chap1 through chap10, the output constructed will be the following:
```
chap1 chap2 chap3 chap4 chap5 chap6 - some files in the directory
chap7 chap8 chap9 chap10 - some file in the directory
```

File

/usr/bin/xargs

Contains the xargs command.

Related Information

The ar command, diff command, echo command, ksh command, lint command, ls command, mv command.

Shells Overview and Commands Overview in AIX 5L Version 5.2 System User's Guide: Operating System and Devices.

Input and Output Handling Programmer's Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.