DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

xargs(C)


xargs -- construct and execute commands

Syntax

xargs [ -tpr ] [ -e [ eofstr ] ] [ -E eofstr ] [ -i [ replstr ] ] [ -I replstr ]
[ -l [ number ] ] [ -L number ] [ -n number [ -x ] ] [ -s size ] [ command [ initial-arguments ] ]

Description

The xargs command combines the fixed initial-arguments with arguments read from the standard input to execute the specified command one or more times. The number of arguments read for each command invocation and the manner in which they are combined are determined by the options specified.

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

If all invocations of the command are successful, xargs terminates with an exit code of 0. However, xargs will terminate immediately if one of the following conditions is true: Otherwise xargs will terminate with an exit code of 1 if one or more invocations of the command returned a non-zero exit code.

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 move all files from directory $1 to directory $2, and echo each move command just before doing it:

ls $1 | xargs -i -t mv $1/{} $2/{}

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

xargs is conformant with:

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


© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003