xargs — Construct an argument list and run a command

xargs gets the needed arguments from standard input (the standard input). Different options tell how the standard input is to be interpreted to obtain these arguments.

–I placeholder

Specifies that each line in the standard input (the standard input) is to be considered as a single argument. The placeholder following the –I is a string that can appear multiple times in the command template. xargs strips the input line of any leading white space characters and inserts it in place of the placeholder string. For example, with:

xargs –I '{}' mv dir1/'{}' dir2/ '{}'

The standard input should consist of lines giving names of files that you want moved from dir1 to dir2. xargs substitutes these names for the {} placeholder in each place that it appears in the command template.

When xargs creates arguments for the template command, no single argument can be longer than 255 characters after the input has replaced the placeholders. The –x option is automatically in effect if –I or –i is used. If you omit the placeholder string, it defaults to the string { }. Thus we could write our preceding example as:

xargs –i mv dir1/ '{}' dir2/ '{}'

In a double-byte locale, placeholder may contain double-byte characters.

–i placeholder

Behaves like –I, except that the placeholder is optional. If you omit the placeholder string, it defaults to the string { }. Thus, the previous example could be written as:

xargs –i mv dir1/ '{{ ' dir2/'{ } '
xargs –i /{}/ mv dir1/ '{}' dir2/ '{}

–L number

Specifies that xargs read number lines from the standard input and concatenate them into one long string (with a blank separating each of the original lines). xargs then appends this string to the command template and runs the resulting command. This process is repeated until xargs reaches the end of the standard input if there are fewer than number lines left in the file the last time the command is run, xargs just uses what is there.

With this option, a line must contain at least one nonblank character; blank lines are skipped and do not count toward the number of lines being added to the template. xargs considers a line to end at the first newline character, unless the last character of the line is a blank or a tab; in this case, the current line is considered to extend to the end of the next non-empty line.

If you omit the –L or –l option, the default number of lines read from the standard input is 1. The –x option is automatically in effect if –l is used.

–l number

Acts like the –L option, but the number argument is optional. number defaults to 1.

–n number

Specifies xargs is to read the given number of arguments from the standard input and put them on the end of the command template. For example:

xargs –n 2 diff

obtains two arguments from the standard input, appends them to the diff command, and then runs the command. It repeats this process until the standard input runs out of arguments. When you use this option, xargs considers arguments to be strings of characters separated from each other by white space characters (blanks, horizontal tabs, or newlines). Empty lines are always skipped (that is, they don't count as arguments). If you want an input argument to contain blanks or horizontal tabs, enclose it in double quotes or single quotes. If the argument contains a double-quote character ("), you must enclose the argument in single quotes. Conversely, if the argument contains a single quote (') (or an apostrophe), you must enclose the argument in double quotes. You can also put a backslash (\) in front of a character to tell xargs to ignore any special meaning the character may have (for example, white space characters, or quotes).

xargs reads fewer than number arguments if:

• The accumulated command line length exceeds the size specified by the –s option (or {LINE_MAX} if you did not specify –s)
• The last iteration has more than zero, but less than number arguments remaining

If you do not specify the –n option, the default number of arguments read from the standard input is 1.

Typically, an xargs command uses exactly one of the options just described. If you specify more than one, xargs uses the one that appears last on the command line. If the command has none of these options, xargs keeps reading input until it fills up its internal buffer, concatenating arguments to the end of the command template. When the buffer is full, xargs runs the resulting command, and then starts constructing a new command. For example:

ls | xargs echo

prints the names of files in the working directory as one long line. When you invoke xargs this way, the total length of all arguments must be less than the size specified by the –s option.

You can use the following options with any of the three main options.

–E [eofstr]

Defines eofstr to represent end-of-file on the standard input. For example:

–E :::

tells xargs that ::: represents the end of the standard input, even if an input file continues afterward. If there is no –E or –e option, a single underscore (_) marks the end of the input.

In a double-byte locale, eofstr may contain double-byte characters.

–e [eofstr]

Acts like –E but the eofstr argument is optional. If you specify –e without eofstr, there is no end-of-file marker string, and _ is taken literally instead of as an end-of-file marker. xargs stops reading input when it reaches the specified end-of-file marker or the true end of the file.

–p

Prompts you before each command. This option turns on the –t option so that you see each constructed command before it is run. Then xargs displays ?…, asking if you really want to run this command. If you type a string beginning with y, xargs runs the command as displayed; otherwise, the command is not run, and xargs constructs a new command.

–s size

Sets the maximum allowable size of an argument list to size bytes (where size is an integer). The value of size must be less than or equal to the system variable LINE_MAX. If you omit the –s option, the default allowable size of an argument list is LINE_MAX. The length of the argument list is the length of the entire constructed command; this includes the length of the command name, the length of each argument, plus one blank for separating each item on the line.

–t

Writes each constructed command to stderr just before running the command.

–x

Kills xargs if it creates a command that is longer than the size given by the –s option (or {LINE_MAX} is –s was not specified). This option comes into effect automatically if you specify –i or –l.

xargs uses the following localization environment variables:

• LANG
• LC_ALL
• LC_CTYPE
• LC_MESSAGES
• LC_SYNTAX
• NLSPATH

0

Successful completion of all commands

1–125

Failure due to any of the following:

• xargs could not assemble a command line
• One or more invocations of command returned a nonzero exit status.
• Some other error occurred

126

xargs found command but could not invoke it

127

xargs could not find command