 |
Index for
Section 1 |
|
 |
Alphabetical
listing for X |
|
 |
Bottom of
page |
|
xargs(1)
NAME
xargs - Constructs argument lists and runs commands
SYNOPSIS
xargs [-e[eofstr]] [-E eofstr] [-i[replstr]] [-I replstr] [-l[number]] [-L
number] [-n[number]] [-ptrx] [-slength] [CommandString] [argument...]
The xargs command constructs a command line by combining a command string,
containing a command and its options or arguments, with additional
arguments read from standard input.
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
xargs: XCU5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
OPTIONS
-eeofstr
Sets the logical end-of-file string to eofstr. The xargs command reads
standard input until it encounters either an end-of-file character or
the logical end-of-file string. If you do (underline). If you specify
-e with no eofstr, xargs interprets the underline character as a
literal character, rather than as an end-of-file marker.
-E eofstr
Specifies a logical end-of-file string to replace the default
underscore. The xargs command reads standard input until either an
end-of-file character or the logical end-of-file string is encountered.
-i[replstr]
Takes an entire line as a single argument and inserts it in each
instance of replstr found in the command string. A maximum of five
arguments in the command string can each contain one or more instances
of replstr. The xargs command discards spaces and tabs at the
beginning of each line. The argument constructed cannot be larger than
255 bytes. The default replstr is {}. This option also turns on the
-x option.
-I replstr
Insert mode: command is executed for each line from standard input,
taking the entire line as a single argument, inserting it in arguments
for each occurrence of replstr. Any blank characters at the beginning
of each line are ignored. Constructed arguments cannot grow larger than
255 bytes. Option -x is forced on. The -I and -i options are mutually
exclusive; the last one specified takes effect.
-l[number]
Runs the command string with the specified number of nonempty argument
lines read from standard input. The last invocation of the command
string can have fewer argument lines if fewer than number remain. A
line ends with the first newline character unless the last character of
the line is a space or a tab. A trailing space or tab indicates a
continuation through the next nonempty line. The default number is 1.
This option turns on the -x option.
-L number
The command is executed for each non-empty number lines of argument
from standard input. The last invocation of command has fewer lines of
argument if fewer than number remain. A line is considered to end with
the first newline character unless the last character of the line is a
blank character. A trailing blank character signals continuation to the
next non-empty line, inclusive. The -L, -l and -n options are mutually
exclusive; the last one takes effect.
-n [number]
Executes the command string using as many standard input arguments as
possible, up to a maximum of number. The xargs command uses fewer
arguments if their total length is greater than the number of
characters specified by the -s [length] option. It also uses fewer
arguments for the last invocation if fewer than number arguments
remain. When -x is present, each number argument must fit the length
limitation specified by -s.
-p Asks whether or not to run the command string. It displays the
constructed command line, followed by a ?... prompt. Press y, or the
locale's equivalent of a y, to run the command string. Any other
response causes xargs to skip that particular invocation of the command
string. You are asked about each invocation.
-s [length]
Sets the maximum total length of each argument list. The length must be
a positive integer less than or equal to 470. The default length is
470 bytes. Note that the character count for length includes one extra
character for each argument and the number of characters in the command
name.
-t Echoes the command string and each constructed argument list to file
descriptor 2 (usually standard error).
-x Stops running xargs if any argument list is greater than the number of
characters specified by the -s length option. This option is turned on
if you specify either the -i or -l options. If you do not specify -i,
-l, or -n, the total length of all arguments must be within the length
limit.
OPERANDS
CommandString
The name of the command to be invoked, found by searching the path
using the PATH environment variable. If CommandString is omitted, the
default is the echo command.
argument
An initial option or operand for the invocation of CommandString.
DESCRIPTION
The xargs command runs the command string as many times as necessary to
process all input arguments. The default command string is echo.
Arguments read from standard input are character strings delimited by one
or more spaces, tabs, or newline characters. You can embed a space or a tab
in arguments by preceding it with a \ (backslash) or by quoting it. The
xargs command reads characters enclosed in single or double quotes as
literals and removes the delimiting quotes. It always discards empty
lines.
The xargs command ends if it cannot run the command string or if it
receives an exit code of -1. When the command string calls a shell
procedure, the shell procedure should explicitly exit with an appropriate
value to avoid accidentally returning -1. (See the sh command.)
The LC_MESSAGES variables determines the locale's equivalent of y and n
(for yes/no queries).
EXIT STATUS
The following exit values are returned:
0 All invocations of CommandString returned exit status zero.
1-125
A command line meeting the specified requirements could not be
assembled, one or more of the invocations of CommandString returned a
non-zero exit status, or some other error occurred.
126 The command specified by CommandString was found but could not be
invoked.
127 The command specified by CommandString could not be found.
EXAMPLES
1. To use a command on files whose names are listed in a file, use a
command line similar to the following:
xargs lint -a < cfiles
If cfiles contains the text, enter:
main.c readit.c
gettoken.c
putobj.c
then xargs constructs and runs the command:
lint -a main.c readit.c gettoken.c putobj.c
Each shell command line can be up to 470 bytes long. If cfiles
contains more file namess than fit on a single line, then xargs runs
the lint command with the file namess that fit. It then constructs
and runs another lint command using the remaining file namess.
Depending on the names listed in cfiles, the commands might look like
the following:
lint -a main.c readit.c gettoken.c...
lint -a getisx.c getprp.c getpid.c...
lint -a fltadd.c fltmult.c fltdiv.c...
This is not quite the same as running lint once with all the file
namess. The lint command checks cross-references between files.
However, in this example it cannot check between main.c and fltadd.c,
or between any two files listed on separate command lines.
For this reason you might want to run the command only if all the file
namess fit on one line. Do this by using xargs with the -x option:
xargs -x lint -a <cfiles
If all the file names in cfiles do not fit on one command line, then
xargs displays an error message.
2. To construct commands that contain a certain number of file namess,
use a command line similar to the following:
xargs -t -n2 diff <<end
starting chap1 concepts chap2 writing
chap3
end
This constructs and runs diff commands that contain two file names
each (-n2):
diff starting chap1
diff concepts chap2
diff writing chap3
The -t option tells xargs to display each command before running it so
that you can see what is happening. The <<end and end arguments
define a Here Document, which uses the text entered before the end
line as standard input for the xargs command. (For more details, see
the section Inline Input (Here) Documents in the sh(1) reference
page.)
3. To insert file namess into the middle of commands, use a command line
similar to the following:
ls | xargs -t -i mv {} {}.old
This renames all files in the current directory by adding .old to the
end of each name. The -i tells xargs to insert each line of the ls
directory listing where { } (braces) appear. If the current directory
contains the files chap1, chap2, and chap3, then this constructs the
following commands:
mv chap1 chap1.old
mv chap2 chap2.old
mv chap3 chap3.old
4. To run a command on files that you select individually, use a command
line similar to the following:
ls | xargs -p -n1 ar r lib.a
This allows you to select files to add to the library lib.a. The -p
option tells xargs to display each ar command it constructs and ask if
you want to run it. Press y, or the locale's equivalent of a y, and
press <Return> to run the command. Press <Return> alone if you do not
want to run it.
ENVIRONMENT VARIABLES
The following environment variables affect the execution of xargs:
LANG
Provides a default value for the internationalization variables that
are unset or null. If LANG is unset or null, the corresponding value
from the default locale is used. If any of the internationalization
variables contain an invalid setting, the utility behaves as if none of
the variables had been defined.
LC_ALL
If set to a non-empty string value, overrides the values of all the
other internationalization variables.
LC_CTYPE
Determines the locale for the interpretation of sequences of bytes of
text data as characters (for example, single-byte as opposed to
multibyte characters in arguments and input files) and the behavior of
character classes used for yesexprlocal keyword in the LC_MESSAGES
category.
LC_MESSAGES
Determines the locale for the format and contents of diagnostic
messages written to standard error.
NLSPATH
Determines the location of message catalogues for the processing of
LC_MESSAGES.
PATH
Determines the location of CommandString.
SEE ALSO
Commands: ksh(1), Bourne shell sh(1b), POSIX shell sh(1p)
Standards: standards(5)
|
Index for
Section 1 |
|
|
Alphabetical
listing for X |
|
 |
Top of
page |
|