xargs(1)
NAME
xargs − construct argument list(s) and execute command
SYNOPSIS
xargs [flags] [command [initial-arguments]]
DESCRIPTION
xargs combines the fixed initial-arguments with arguments read from 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 flags specified.
command, which can be a shell file, is searched for, using the $PATH environment 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 new-lines; empty lines are always discarded. Spaces and tabs can 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 (\) escapes the next character.
The amount of memory available for the execution of command is limited by the system parameter ARG_MAX. By default, the size of the argument list is limited to LINE_MAX bytes. See limits(5) and sysconf(2) for a description of these system parameters and how their values can be determined. To increase the available argument list space, use the −s option.
Each argument list is constructed starting with the initial-arguments, followed by some number of arguments read from standard input (exception: see −i flag). The −i, −l, and −n options determine how arguments are selected for each command invocation. When none of these options is specified, the initial-arguments are followed by arguments read continuously from standard input until an internal buffer is full, then command is executed with the accumulated args. This process is repeated until there are no more args. When there are flag conflicts (such as −l versus −n), the last flag has precedence. flag values are:
−l number command is executed for each non-empty number lines of arguments from standard input. 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 new-line unless the last character of the line is a blank or a tab; a trailing blank/tab signals continuation through the next non-empty line. 1 is assumed if number is omitted or is given as the empty string ( Option −x is forced.
−i replstr Insert mode: command is executed for each line from standard input, taking the entire line as a single arg, inserting it in initial-arguments for each occurrence of replstr. A maximum of 5 arguments in initial-arguments can each contain one or more instances of replstr. Blanks and tabs at the beginning of each line are discarded. Constructed arguments must not grow larger than 255 characters, and option −x is also forced. {} is assumed if replstr is omitted or is given as the empty string ( "" ).
−n number Execute command using as many standard input arguments as possible, up to number 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 arguments must fit in the size limitation or xargs terminates execution.
−s size The maximum total size of each argument list is set to size characters; size must be a positive integer less than LINE_MAX (see limits(5), sysconf(2)). If −s is not coded, LINE_MAX is taken as the default. Note that the character count for size includes one extra character for each argument and the count of characters in the command name.
−t Trace mode: The command and each constructed argument list are echoed to standard error just prior to their execution.
−p Prompt mode: The user is asked whether to execute command prior to each invocation. Trace mode (−t) is turned on to print the command instance to be executed, followed by a ?... prompt. A reply of y (optionally followed by anything) executes the command; anything else, including pressing Return, skips that particular invocation of command.
−x Causes xargs to terminate if any argument list would be greater than size characters. −x is forced by the options −i and −l. When none of the options −i, −l, or −n is coded, the total length of all arguments must be within the size limit.
−e eofstr eofstr is taken as the logical end-of-file string. Underscore (_) is assumed for the logical EOF string if −e is not coded. The value −e with eofstr given as the empty string ("") turns off the logical EOF string capability (underscore is taken literally). xargs reads standard input until either end-of-file or the logical EOF string is encountered.
xargs terminates if it receives a return code of −1 from command or if it cannot execute, command. When command is a shell program, it should explicitly exit (see sh(1)) with an appropriate value to avoid accidentally returning with −1.
RETURN VALUE
xargs exits with one of the following values:
0 All invocations of command completed successfully.
>0 One or more invocations of command did not complete successfully.
EXAMPLES
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/{}
Combine the output of the parenthesized commands onto one line, then echo to the end of file log:
(logname; date; echo $0 $∗) | xargs >>log
Ask the user which files in the current directory are to be archived then archive them into arch (1) one at a time, or (2) many at a time.
1: ls | xargs −p −l ar r arch
2: ls | xargs −p −l | xargs ar r arch
Execute diff(1) with successive pairs of arguments originally typed as shell arguments:
echo $∗ | xargs −n2 diff
SEE ALSO
STANDARDS CONFORMANCE
xargs: SVID2, XPG2, XPG3, proposed POSIX.2 FIPS (June 1990)
Hewlett-Packard Company — HP-UX Release 8.05: June 1991