xargs -- construct and execute command lines

SYNOPSIS

xargs [-I placeholder] [-i[placeholder]] [-L number] [-l[number]] [-n number] [-ptx] [-E [eofstr]] [-e[eofstr]] [-s size] [command [argument ...] ]

DESCRIPTION

The xargs command line typically contains the skeleton or template of another command. This template looks like a normal command, except that it is lacking some arguments. xargs adds arguments from the standard input to complete the command, then executes the resulting command. If more input remains, it repeats this process.

Note:: Undefined behavior may occur if command reads from the standard input.

Options

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

-I placeholder

causes xargs to consider each full line in the standard input to be 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 (described below) is automatically in effect if -I or -i is used.

-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

reads number lines from the standard input and concatenates them into one long string (with a blank separating each of the original lines). xargs then appends this string to the command template and executes the resulting command. This process is repeated until xargs reaches to the end of the standard input. If there are fewer than number lines left in the file the last time the command is executed, xargs uses whatever is available.

With this option, a line must contain at least one non-blank character; blank lines are skipped and do not count towards 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 which case, the current line is considered to extend to the end of the next non-empty line.

If you omit the -L option, the default number of lines read from standard input is 1. The -x option (described in a following paragraph) is automatically in effect if -L or -l is used.

-lnumber

acts like the -L option, but the number argument is optional. number defaults to 1.

-n number

reads a maximum of number arguments from the standard input and puts them on the end of the command template. For example, in

xargs -n 2 diff

obtains two arguments from the standard input, appends them to the diff command, and executes the command. 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).

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 want an input argument to contain blanks or horizontal tabs, enclose it in double quotes or apostrophes. If the argument contains a double quote character ("), you must enclose the argument in apostrophes. Conversely, if the argument contains 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).

Typically, an xargs command must use exactly one of the preceding options. If you specify more than one, xargs uses the one that appears last on the command line. If you do not specify any of these options, xargs keeps reading input until it fills up its internal buffer, concatenating arguments onto the end of the command template. When the buffer is full, xargs executes the resulting command, then starts constructing a new command. For example,

ls | xargs echo

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

If no command template appears on the command line, xargs uses echo by default. When xargs executes a command, it uses your search rules to find the command; this means that you can run shell scripts as well as normal programs.

Note that the command you want to execute should be in your search PATH.

xargs terminates prematurely if it cannot execute a constructed command or if an executed command returns a non-zero status value. If an executed command is a shell program, it should explicitly contain an exit command to avoid returning a non-zero status value by accident; see sh for details.

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 it is not at the end of the file. If there is no -E or -e option, a single underscore (_) marks the end of the input.

-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 turns on the -t option so that you see each constructed command before it is executed. Then, xargs displays ?..., asking if you really want to executed this command. If you type a string beginning with y, xargs goes ahead and executes the command as displayed; otherwise, the command is not executed, and xargs goes on to construct a new command.

-s size

sets the maximum allowable size of an argument list to size characters (where size is an integer). The value of size must be less than or equal to the system variable 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 the standard error just before executing the command.

-x

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

EXAMPLES

The following displays file names in three columns:

ls | xargs -n 3 echo

ENVIRONMENT VARIABLES

PATH: contains a list of directories that constitute your search path.

DIAGNOSTICS

Possible exit status values are:

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 non-zero exit status

— some other error occurred

126

xargs found command but could not invoke it.

127

xargs could not find command.

PORTABILITY

POSIX.2. x/OPEN Portability Guide 4.0. All UNIX systems. Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.

The -E, -e, -I, -i, -l, -L, and -p options are extensions to the POSIX standard.

The x/OPEN standard states that the -I and -i options are limited to five arguments, and that the total size of the constructed arguments cannot exceed 255 bytes. As an extension to the standard, these limits do not apply to this implementation of xargs. There is no limit on the number of arguments for -I; this is an extension to the x/OPEN standard.

LIMITS

The maximum length of a constructed command is LINE_MAX characters.

AVAILABILITY

PTC MKS Toolkit for Power Users
PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

xargs
construct and execute command lines

Command