XARGS(1) XARGS(1) NAME xargs - construct argument list(s) and execute command SYNOPSIS xargs [options] [ command [initial-arguments] ] DESCRIPTION xargs constructs a command line consisting of the command and initial- arguments operands specified followed by as many arguments read in sequence from standard input as will fit in length and number constraints specified by the options. xargs then invokes the constructed command line and waits for its completion. This sequence is repeated until an end-of-file condition is detected on standard input or an invocation of a constructed command line returns an exit status of 255. command, which may be a shell file, is searched for, using one's $PATH. 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. 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. The generated command line length will be the sum of the size in bytes of the command name and each argument treated as strings, including a null byte terminator for each of these strings. The xargs command will limit the command line length such that when the command line is invoked, the combined argument and environment lists will not exceed ARG_MAX-2048 bytes. Within this constraint, if neither the -n nor the -s option is specified, the default command line length will be at least LINE_MAX. OPTIONS -Lnumber 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. -l[number] Same as -L, except: if number is omitted, 1 is assumed; option -x is forced. -Ireplstr 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 may each contain one or more instances of replstr. Blanks and tabs at the beginning of each line are ignored. Constructed arguments may not grow larger than what the kernel ncargs value allows (the default as shipped is 20480), including room for pointers. This may be further reduced, depending on environment size and other arguments), and option -x is forced. -i[replstr] Same as -I except that {} is assumed for replstr if omitted. The -I and -i options are mutually exclusive; the last one specified takes effect. -nnumber Execute command using as many standard input arguments as possible, up to number arguments maximum. Fewer arguments will be used if their total size is greater than size characters, and for the last invocation if there are fewer than number arguments remaining. In any case, a maximum of 1024 arguments will be passed per command invocation. This is further reduced by any extra command arguments given on the xargs command line. If option -x is also coded, each number arguments must fit in the size limitation, else xargs terminates execution. The -L, -l and -n options are mutually exclusive; the last one specified takes effect. -t Trace mode: The command and each constructed argument list are echoed to file descriptor 2 just prior to their execution. -p Prompt mode: The user is asked whether to execute command 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) will execute the command; anything else, including just a carriage 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 neither of the options -i, -l, or -n are coded, the total length of all arguments must be within the size limit. -ssize Invoke command using as many standard input arguments as possible yielding a command line length less than size (a positive decimal integer) bytes. Fewer arguments will be used if the total number of arguments (lines) exceeds that specified by the -n (-L) option or end of file is encountered on standard input before size bytes are accumulated. The maximum size depends partly on the size of the environment, but is limited to a maximum of the kernel value of ncargs (the default as shipped is 20480), including room for pointers. If -s is not coded, the maximum is taken as the default. -Eeofstr Specify a logical end-of-file string to replace the default underscore. xargs reads standard input until either end-of-file or the logical EOF string is encountered. -e[eofstr] Same as -E except that the option -e with no eofstr coded turns off the logical EOF string capability (underbar is taken literally). Note: The -e, -i and -l take optional option-arguments that cannot be separate arguments. xargs will terminate if either it receives a return code of -1 from, 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. 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/{} or 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 asked which files in the current directory are to be archived and archives 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 The following will execute diff(1) with successive pairs of arguments originally typed as shell arguments: echo $* | xargs -n2 diff DIAGNOSTICS xargs exits with 0 when all invocations of command returned exit status zero. xargs exits with 126 when the command specified was found but could not be invoked. xargs exits with 127 when the command specified could not be found. SEE ALSO sh(1). Page 3