xargs Command

Purpose

Constructs parameter lists and runs commands.

Syntax

xargs [-p t x ] [-e [EOFString]] [-E EOFString] [-i [ReplaceString] ] [-I ReplaceString | -L Number | -n Number] [ -l [ Number]] [-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

Item	Description
-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), i, -L (uppercase l) , l, and -n 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. The -I (uppercase i) flag means -L1. Therefore, only one standard input line can be substituted as an argument at a time. If the replaced string appears more than once in the command parameter, the same standard input line is substituted for each occurrence of the replaced string. Note: The -I (uppercase i), i, -L (uppercase l) , l, and -n 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 -I (uppercase i), i, -L (uppercase l), -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. Reads the Number lines from the standard input and places them at the end of the command line. Note: The -I (uppercase i), i, -L (uppercase l), -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. Reads the maximum of Number arguments from the standard input and places them at the end of the command line. The xargs command uses fewer arguments if: The accumulated command line length exceeds the bytes specified by the -s Size flag. The last iteration has fewer value than the value specified by the Number argument, but not zero, arguments remaining. Note: The -I (uppercase i), i, -L (uppercase l), -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 -l (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:

Item	Description
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 files in the directory
```

File

Item	Description
/usr/bin/xargs	Contains the xargs command.