xargs combines command-line arguments with arguments that it reads from standard input and executes the specified command one or more times. The number of arguments read for each command invocation and the manner in which they are combined can be determined by the options specified.
Arguments read in from standard input are defined to be contiguous strings of characters delimited by one or more blanks, tabs, or newline characters; empty lines are discarded. Blanks and tabs may be embedded as part of an argument only if they are either escaped with a backslash \ or if the argument is enclosed in single or double quotes (’...’ or "..."). Otherwise, they are interpreted as separators between arguments. The usual quoting mechanisms apply as well, i.e. metacharacters are also escaped as mentioned above.
Syntax
xargs[ option]...[ command[ initial_argument]...] |
Options -I (or -i), -L (or -l) and -n determine how the command-line arguments and the arguments read from standard input are to be selected for each invocation of command. If none of the -I (or -i), -L (or -l) or -n options are used: The initial arguments specified in the xargs command line are followed by arguments read continuously from standard input until an internal buffer is full. command is then executed with the accumulated arguments. This process is repeated until there are no more arguments. If combinations of the -I (or -i), -L (or -l) or -n options are used: When there are conflicts (e.g. -l and -n), the last specified option takes effect.
Insert mode; command is executed for each line read from standard input, taking each line as an argument and inserting it for each occurrence of repstr in the list of initial arguments specified when xargs was called. A maximum of 5 arguments in the list of initial arguments may each contain one or more instances of repstr. Blanks and tabs at the beginning of each line are ignored. Constructed arguments may not grow larger than 255 characters. The -I option automatically also sets the -x option. This corresponds to the old option -i, which is still supported. For repstring , braces {} are assumed in the case of -i if not explicitly specified.
command is executed for every number non-empty argument lines that xargs reads from standard input. If fewer than number lines remain when command is invoked for the last time, command will be executed with these lines. A line is considered to end with the first newline character in it unless the last character in the line is a blank or a tab. A trailing blank or tab signals continuation to the next non-empty line. The -L option automatically also sets the -x option. This corresponds to the old option -l, which is still supported. If number is not specified for -l, the value 1 is assumed.
Executes command using as many standard input arguments as possible (up to a maximum of number). Fewer arguments will be used if their total size is greater than maxsize characters (see -s option). If fewer than number arguments remain for the last invocation, these arguments will be used. If option -x is also set, each number arguments must not exceed the maximum limitation specified with maxsize (see option -s), as otherwise xargs will terminate execution.
Defines eofstr as the logical end-of-file string. xargs reads from standard input until either the actual end-of-file or the logical eofstr is encountered. Specify a string of eofstr. This string is interpreted as the logical end-of-file string when xargs is executed. This corresponds to the old option -e, which is still supported. If -e is specified without eofstr, a logical end-of-file string is no longer specified. The underscore _ has no special meaning and is processed as a normal character. Neither -E nor -e specified:
Prompt mode; the user is asked whether to execute command at each invocation. In addition, the trace mode (option -t) is turned on to print the invoked command, followed by a ?... prompt.
Sets the maximum number of characters in each argument list to maxsize (an argument list is a combination of arguments formed on the basis of rules defined by the -I (or -i), -L (or -l), or -n options). Note that the character count for maxsize includes one extra character for each argument and the count of characters in the command name.
Trace mode; the command and each constructed argument list are echoed to standard error just prior to their execution.
Causes xargs to terminate if any argument list would exceed the specified maximum of maxsize characters (see option -s). The -x option is forced when options -I (or -i) and -L (or -l) are set. When none of the -I (or -i), -L (or -l) or -n options are coded, the execution of xargs is terminated if the total length of all arguments exceeds maxsize characters (see option s).
Any command may be specified for command. xargs will terminate if it receives an exit status of 255 from command or cannot execute it. If command is a shell script, it should include an exit command which explicitly returns a suitable exit status so as to avoid accidentally returning with 255 (e.g. exit -1). command not specified:
Argument lists are constructed (as described above) by combining initial arguments specified on the xargs command line with arguments read from the standard input (see options -I (or -i), -L (or -l) and -n). The specified command is then executed with these argument lists. The initial arguments always appear at the beginning of an argument list, except when the -I or -i option is set. initial_argument not specified: |
Exit status
| 0 | Each call of command returned the exit status 0. |
| 1-125 | The arguments could not be combined as requested, or at least one call of command returned a non-zero exit status or a further error occurred. |
| 126 | The specified command exists, but cannot be executed. |
| 127 | The specified command cannot be found. |
Locale
The following environment variables affect the execution of xargs: LANG Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined. LC_ALL If set to a non-empty string value, override the values of all the other internationalization variables. LC_COLLATE Determine the locale for the behavior of ranges, equivalence classes and multicharacter collating elements used in extended regular expressions defined for the yes/no queries. LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments) and the behavior of character classes used in extended regular expressions defined for the yes/no queries. LC_MESSAGES Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error. NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. |
Example 1
The following shell script named relocate moves files with names that do not begin with a period (.) from one directory to another:
|
Example 2
The following shell script named who_and_when collects the output of the parenthesized commands (...) in one line and appends this line to the end of the file log:
|
Example 3
The following shell script named archive places files in the current directory whose names do not begin with a period (.) in an archive named archive.a (see ar):
ls displays the contents of the current directory on standard output with one file name in each line. xargs then calls ar with the arguments r, archive.a, and each file name returned by ls. Since the -p option has been set, you are asked whether or not the corresponding ar command is to be executed in each case. If you respond with a "y" the first time, ar creates the archive file archive.a, issues a corresponding message, and saves the current file in it. Your subsequent responses to each prompt will then determine which files are to be stored in archive.a. If required, the contents of archive.a can be listed at the end with the ar t command. |
See also
| echo |