xargs(C)

Syntax

Description

command, which may be a shell file, is searched for using the shell $PATH variable. If command is omitted, /bin/echo is used.

Arguments read in from standard input are defined to be contiguous strings of characters delimited by one or more blanks, tabs, or newlines; empty lines are always discarded. Blanks and tabs may be embedded as part of an argument if escaped or quoted: Characters enclosed in quotes (single or double) are taken literally, and the delimiting quotes are removed. Outside of quoted strings, a backslash (\) will escape the next character.

Each argument list is constructed starting with the initial-arguments, followed by some number of arguments read from standard input (exception: see the -i, -r and -I options).

Options -i, -I, -r, -l, -L, and -n determine how arguments are selected for each command invocation.

There must not be any space between the options -e, -i, and -l and their optional parameters.

When no options are coded, the initial-arguments are followed by arguments read continuously from standard input until an internal buffer is full, and command is executed with the accumulated arguments. This process is repeated until there are no more arguments. When there are option conflicts (for example, -l and -n), the last specified option has precedence.

xargs takes the following options:

-e[eofstr]

Use eofstr as the logical end-of-file (EOF) string. xargs reads standard input until either end-of-file or the logical EOF string is encountered. The default logical EOF string is underscore (_) if neither -e nor -E is specified. If -e is specified but eofstr is not, underscores are treated as literal characters.

-E eofstr

Specify eofstr as the logical EOF string instead of underscore. xargs reads standard input until either end-of-file or the string specified by eofstr is encountered.

-i[replstr]

Insert mode: command is executed for each line from the standard input, taking the entire line as a single argument, inserting it in initial-arguments for each occurrence of replstr. A maximum of 5 arguments in initial-arguments may each contain one or more instances of replstr. Blanks and tabs at the beginning of each line are thrown away. Constructed arguments may not grow larger than 255 characters, and option -x is also forced. ``{}'' is assumed for replstr if not specified.

-I replstr

Similar to the -i option, except that replstr must be present.

-l[number]

command is executed for each number lines of nonempty arguments from the standard input. This is instead of the default single line of input for each command. The last invocation of command will be with fewer lines of arguments if fewer than number remain. A line is considered to end with the first newline unless the last character of the line is a blank or a tab; a trailing blank/tab signals continuation through the next nonempty line. If number is omitted, 1 is assumed. Option -x is forced.

-L number

Similar to the -l option, except that number must be present and the -x option is not forced.

-n number

Executes command, using as many standard input arguments as possible, up to the number of arguments maximum. Fewer arguments are used if their total size is greater than size characters, and for the last invocation if there are fewer than number arguments remaining. If option -x is also coded, each number of arguments must fit in the size limitation, or xargs terminates execution.

-p

Prompt mode: the user is prompted whether to execute command at each invocation. Trace mode (-t) is turned on to display the command instance to be executed, followed by a ``?...'' prompt. A positive reply (as defined by the current locale) will execute the command; anything else, including a carriage return, skips that particular invocation of command.

-r

Equivalent to -I {}.

-s size

The maximum total size of each argument list is set to size characters; size must be a positive integer less than or equal to 2048. If -s is not coded, 2048 is taken as the default. Note that the character count for size includes one extra character for each argument, the count of characters in the command name, and the terminating NULL character.

-t

Trace mode: the command and each constructed argument list are echoed to file descriptor 2 just prior to their execution.

-x

Causes xargs to terminate if any argument list would be greater than size characters; -x is forced by the options -i, -I, and -l. When none of the options -i, -I, -L, -l, or -n are coded, the total length of all arguments must be within the size limit.

Exit values

• A command terminated with an exit code of 255.xargs will return an exit code of 1.

• A command was found but could not be invoked, or the command returned an exit code of 126. xargs will return an exit code of 126.

• A command was not found, or the command returned exit code 127. xargs returns an exit code of 127.

• The command received a signal, or a command line meeting the specified requirements could not be made. xargs will return an exit code of 1.

When command is a shell program, it should explicitly exit (see sh(C)) with an appropriate value to avoid accidentally returning with an exit code of 255, 126 or 127.

Examples

The following will combine the output of the parenthesized commands onto one line, which is then echoed to the end-of-file log:

(logname; date; echo $0 $) | xargs >>log

The user is prompted to enter which files in the current directory are to be printed and prints them one at a time:

ls | xargs -p -l lpr

or many at a time:

ls | xargs -p -l | xargs lpr

The following will execute diff(C) with successive pairs of arguments originally entered as shell arguments:

echo $ | xargs -n2 diff

Standards conformance

ISO/IEC DIS 99452:1992, Information technology Portable Operating System Interface (POSIX) Part 2: Shell and Utilities (IEEE Std 1003.21992);
AT&T SVID Issue 2;
X/Open CAE Specification, Commands and Utilities, Issue 4, 1992.