8.4.41 xargs command (creates and runs a command line)
Syntax
xargs [-0] [-r] [-x] [-d delimiter] [-n maximum-number-of-command-arguments]
[-s maximum-command-line-length] [--cmdrc-threshold=threshold]
[external-command-name [external-command's-argument ...]
Description
This command inputs command arguments from the standard input, and then creates and runs a command line.
For details about how to input command arguments, see Input of command arguments.
If the length of the command line to be created exceeds the maximum length of a command line, adjust the number of command arguments in the command line. Then, repeat the process for creating and running the command line. For details about the maximum length of a command line, see Maximum length of a command line.
- Input of command arguments
-
In the standard input, character strings separated by command argument separators are selected as command arguments to be input from the standard input.
Command argument separators are space (0x20), tab character (0x09), and linefeed character. In Windows, [CR]+[LF] (0x0d0a) or [LF] (0x0a) is considered a linefeed character. In UNIX, [LF] (0x0a) is considered a linefeed character. If these separators appear in succession, they are handled as a single separator. You can change command argument separators by using the -0 option or -d option.
The following characters have special meanings for input of command arguments.
Table 8‒23: Special characters that have meaning for input of command arguments Special character
Meaning
'
The following characters contained in a character string enclosed in single quotation marks (') are handled as characters contained in the command argument.
-
Command argument separators (excluding linefeed characters)
-
Other special characters
"
The following characters contained in a character string enclosed in double quotation marks (") are handled as characters contained in the command argument.
-
Command argument separators (excluding linefeed characters)
-
Other special characters
\
A backslash (\) that precedes the following characters disables their spacial meaning (escape characters).
-
Command argument separators
-
Special character
The following characters must be considered during input of command arguments.
-
NULL (0x00)
This character cannot be included in a character string in a command argument. If neither of the following options is specified and NULL(0x00) is input from the standard input, the input process terminates:
- -0 option
- -d option for which a delimiter such as \0 indicating NULL(0x00) is specified
-
Formfeed character (0x0c), carriage return character (0x0d), and vertical tab character(0x0b)
These characters are placed at the beginning of the command arguments separated by separators, those characters are not included in the character string in the command argument.
Example: A formfeed character is represented as \f, a carriage return character is represented as \r, a vertical tab character is represented as \v, and a space is represented as ∆.
- Contents of the standard input
\f\f\rABC\vDEF∆\vGHI\fJKL
- Contents of the command argument array (argv) that is passed to an external command
Command argument array (argv)
Contents of command argument
First
External command name
Second
ABC\vDEF
Third
GHI\fJKL
A command line is also created and run if a command argument is not input from the standard input due to the following causes:
-
The input from the standard input contains zero byte.
-
Only command argument separators are input.
If you do not want a command line to be created and run when a command argument is not input from the standard input, specify the -r option.
For details about the notes on input of command arguments, see Notes.
-
- Command line length
-
In UNIX, the unit of the command line length is bytes.
In Windows, the command line length is expressed in characters. A multibyte character is counted as one character.
The command line length is the total length of the following character strings. The length of a character string includes NULL (0x00), which indicates the end of the character string.
-
External command name
-
The command arguments of the external command name specified for the xargs command argument
-
The command arguments input from the standard input
In Windows, the following number of characters are added according to the contents of the character string.
Contents of the character string
Number of characters to be added
A space character (0x20)# or a tab character (0x09)# is included.
2
Double quotation marks (")# are included.
1
A double quotation mark (")# is preceded by at least one backslash (\)#.
- For only one backslash (\): 1
- For consecutive backslashes (\): Number of backslashes (\)
The character string ends with at least one backslash (\)# and includes a space character (0x20)#.
- For only one backslash (\): 1
- For consecutive backslashes (\): Number of backslashes (\)
- #
-
When the string is handled as a character string in the command argument for special characters indicated in Special characters that have meaning for input of command arguments, or for the -0 or -d option.
-
- Maximum length of a command line
-
If the length of the command line indicated by Command line length exceeds the maximum length of a command line, adjust the number of command arguments in the command line. Then, re-create the command line and run the command again.
If you do not specify the -s option, the default value is applied for the maximum length of a command line. The default of the maximum length of a command line is determined by the maximum length of a command line that can run in the system. The following describes the maximum length of a command line and the maximum length of a command line that can run in the system.
[In UNIX]
The default of the maximum length of a command line is as follows according to the maximum length of a command line that can run in the system.
Condition
Maximum length of a command line to be used
Maximum length of a command line that can run in the system ≥ 131072
131072 bytes (128 KB)
Maximum length of a command line that can run in the system < 131072
Maximum length of a command line that can run in the system
The maximum length of a command line that can run in the system is obtained by using the following formula.
maximum-length-of-a-command-line-that-can-run-in-the-system# = A - E - 8192
Legend:
A: ARG_MAX value of the system
E: Total size of environment variables that are set at runtime of an external command
#
This value is truncated at the decimal point.
- Important
-
- In a 64-bit edition of Linux, if a value exceeding 1 GB is specified for the ARG_MAX value, 1 GB minus 1 byte is set for the ARG_MAX value.
- In Solaris, the value applicable to a 32-bit program is set for the ARG_MAX value.
In Solaris, create a command line so that the sum of the following values 1 and 2 does not exceed the maximum length of a command line.
1. The value indicated in Command line length
2. Four bytes for each of the following character strings:
- External command name
- Command argument of the external command specified for the argument of the xargs command
- Command argument input from the standard input
[In Windows]
The maximum length of a command line is 32,760 characters. This value is the same as the maximum length of a command line that can run in the system.
If the number of command arguments included in the command line is 1, note that if the length of the command line exceeds the maximum, the command terminates with an error.
Arguments
-0
- --null
-
Sets NULL (0x00) as a command argument separator.
When command arguments are input from the standard input, character strings separated by NULL (0x00) are handled as a single command argument.
Default command line argument separators and special characters indicated in Special characters that have meaning for input of command arguments are handled as characters contained in the command argument.
A character string input from the standard input might contain NULL (0x00) that is not preceded by a character other than NULL (0x00). In this case, the command argument that only contains NULL (0x00), indicating the end of the character string, is passed to an external command.
(Example)
Indicate NULL in \0.
-
Contents of the standard input
abc\0\0def
-
Contents of the command argument array (argv) that is passed to an external command
Command argument array (argv)
Contents of command argument
First
external-command-name\0
Second
abc\0
Third
\0
Fourth
def\0
If the -0 and -d options are specified at the same time, the last specified option is valid.
-
-r
- --no-run-if-empty
-
Does not run the external command if a command argument is not input from the standard input. For details about the input of command arguments, see Input of command arguments.
-x
- --exit
-
Terminates the command with an error if the length of the created command line exceeds the permitted maximum length.
This option takes effect if the -n option is specified at the same time. For details about the operation when this option is specified together with the -n option, see the description of the -n option.
-d delimiter
- --delimiter=delimiter
-
Sets the specified delimiter as a command argument separator.
When command arguments are input from the standard input, character strings separated by delimiter are handled as a single command argument.
Default command line argument separators and special characters indicated in the table Special characters that have meaning for input of command arguments are handled as characters contained in the command argument.
Only single-byte characters can be specified for delimiter. If the length of the specified delimiter is not 1 byte, the command terminates with an error.
The following escape characters can also be specified.
Escape character
Meaning
\a
Alert character (bell)
\b
Backspace character
\f
Formfeed character (page break)
\n
Linefeed character
\r
Carriage return character
\t
Tab character
\v
Vertical tab character
\d, \dd, \ddd
ASCII code characters displayed in octal notation (d: 0 to 7) with 1 to 3 digits
\xh, \xhh
ASCII characters displayed in hexadecimal notation (h: 0 to 9, a to f, and A to F) with 1 or 2 digits
In the character string input from the standard input, the specified delimiter might not be preceded by a character other than a delimiter. In this case, the command argument that only contains NULL (\0) indicating the end of the character string is passed to an external command.
(Example) Indicate NULL in \0. The specified delimiter is indicated in X.
-
Contents of the standard input
abcXXdef
-
Contents of the command argument array (argv) that is passed to an external command
Command argument array (argv)
Contents of command argument
First
external-command-name\0
Second
abc\0
Third
\0
Fourth
def\0
If the -d and -0 options are specified at the same time, only the last specified option is valid.
-
-n maximum-number-of-command-arguments
- --max-args=maximum-number-of-command-arguments
-
Specifies the maximum number of command arguments that can be contained in a command line.
The maximum number of command arguments to be specified does not include the following arguments:
-
External command name
-
Command argument of the external command specified in the command line of the xargs
You can specify the maximum number of command arguments in the range from 1 to 2147483647. If the length of the command line containing the maximum number of command arguments exceeds the permitted maximum length, create a command line with fewer command arguments so that it does not exceed the maximum length.
If the -x option is specified at the same time, the command terminates with an error if the length of the command line containing the maximum number of command arguments exceeds the maximum length of a command line.
-
-s maximum-command-line-length
- --max-chars=maximum-command-line-length
-
Specifies the maximum length of a command line that can be created.
In UNIX, the unit of the command line length is bytes.
In Windows, the command line length is expressed in characters. A multibyte character is counted as one character.
You can specify the maximum length in the range from 1 to the maximum length of a command line that can run in the system indicated in Maximum length of a command line.
If the specified maximum length exceeds the maximum length of a command line that can run in the system (indicated in Maximum length of a command line), the following error message is output to the standard error output: xargs: The value specified for the option -s exceeds the maximum length (maximum-length-of-a-command-line-that-can-run-in-the-system) of the command line in the system. In addition, the maximum length of a command line that can run in the system is set to the maximum length of a command line.
- --cmdrc-threshold=threshold
-
If you want to assume normal termination even if the return code of an external command is not 0, specify the threshold. This causes normal termination if the return code of the external command is equal to or smaller than the threshold.
You can specify the threshold in the range from 0 to 254 in UNIX, and in the range from 0 to 2147483647 in Windows.
The subject to the threshold is only the return code of the external command when the xargs command sets 123 for the return code.
For details about handling of return codes of external commands, see Return codes.
- external-command-name
-
Specify the name of the external command to be run in the command line.
If external-command-name contains no path, the external command found according to the path search order of the OS file run function (execvp function in UNIX or CreateProcess function in Windows) is run.
If external-command-name is omitted, the command argument is output as is to the standard output. Escape characters in the command argument are also output as they are. Note that 5 is added to the value of Command line length as the length of the character string for the command name.
- external-command-argument
-
Specify the command argument to be added after the external command name in the command line.
Command arguments input from the standard input are added after this command argument. If the command line is created and run several times, this command argument is included in each command line.
Return codes
|
Return code |
Meaning |
|---|---|
|
0 |
Normal termination |
|
1 |
Error termination An error occurred during xargs command processing. |
|
123 |
If processing for creating and running the command line must be performed several times, processing continues. |
|
124 |
|
|
125 |
|
|
126 |
The external command could not run. In UNIX, this return code is set if the return code of the external command is 126. |
|
127 |
The external command was not found. In UNIX, this return code is set if the return code of the external command is 127. |
- #1
-
The trailing eight bits of the value returned by the external command are handled as the return code.
- #2
-
The value returned by the external command are handled as a signed integer.
- #3
-
If the external command terminated due to immediate termination of process by, for example, TerminateProcess, the code set by this immediate termination operation is used as the return code of the external command.
Notes
-
If both of the following options are not specified and the character string input from the standard input contains NULL (0x00), the characters up to NULL (0x00) are used to create and run the command line. The portion of the character string following NULL (0x00) is ignored.
-
-0 option
-
The -d option for which a delimiter such as \0 indicating NULL(0x00) is specified
For details about handling of NULL (0x00), see Input of command arguments.
-
-
In Windows, if a path name is input as a command argument from the standard input, a directory-separator backslash (\) and the beginning \\ that indicates the path name in UNC format are handled as escape characters. Therefore, perform one of the following:
-
Use a special character in the table in Special characters that have meaning for input of command arguments to handle a backslash (\) as a character.
-
Specify the -0 option. In addition, use NULL (0x00) as the separator for path names in the standard input. For example, if the file search results output by the find command are to be input by the xargs command, specify -print0 for a search pattern of the find command.
-
Specify the -d option. In addition, use the delimiter specified for the -d option as the separator for path names in the standard input. For example, if the file search results output by the find command are to be input by the xargs command, specify \n (linefeed character) for the -d option.
-
-
In Windows, if you use a special character to include a linefeed character in the command argument, the linefeed character passed to the external command is [LF] (0x0a).
-
In Windows, the input process terminates if 0x1a code is input from the standard input.
-
When the command line runs, the following file is set as the standard input of the external command.
-
In UNIX: /dev/null file
-
In Windows: NUL device
If /dev/null file or NUL device does not exist in the system, the following message is output to the standard error output: xargs: Failed to open a null file when executing the external command external-command-name (error=error-details). The command line is run after the standard input of the external command is closed.
-
-
To run a program from the external command, make sure that the maximum length of a command line for the OS is not exceeded when arguments are passed from the external command to the program. If the maximum length of a command line for the OS is exceeded, the program fails to run.
-
If the external command returns a value other than 0, indicating normal termination, the return code of the xargs command is set to 123. If you want to set the return code of the xargs command to 0, use the --cmdrc-threshold option. For details about handling of return codes of external commands, see Return codes.
-
For some external commands, the maximum length of a command line for the external command might be less than the default maximum length indicated in Maximum length of a command line. In such cases, specify the maximum length of a command line for the external command in the -s option.
-
If the maximum number of command arguments is specified for the external command, use the -n option, and then make sure that the number of command arguments in the command line does not exceed the maximum.
Examples
Receive the path names of files obtained by the find command, and then run the rm command with those path names specified for the operand. Specify as follows to prevent directory separators from being handled as escape characters.
-
For a search pattern of the find command, specify -print0.
-
For an option of the xargs command, specify -0.
If the file is not found by the find command with the -r option specified, the rm command is not run.
C:\TEMP>%ADSH_OSCMD_DIR%\ls "C:\Program TEMP" cmd001.log file001.tmp file002.tmp file003.tmp file004.tmp file005.tmp file006.tmp C:\TEMP>%ADSH_OSCMD_DIR%\find "C:\Program TEMP" -name "*.tmp" -print0 | %ADSH_OSCMD_DIR%\xargs -0 -r %ADSH_OSCMD_DIR%\rm -f C:\TEMP>%ADSH_OSCMD_DIR%\ls "C:\Program TEMP" cmd001.log