OSF

NAME

xargs − Constructs argument lists and runs commands

SYNOPSIS

xargs [−e[eof-string]] [−i[replace-string]] [−l[number]] [−n[number]]
     [−ptx] [−s[length]] command [argument ...]

The xargs command constructs a command line by combining a command string, containing a command and its flags or arguments, with additional arguments read from standard input. 

FLAGS

-e[eof_string]
Sets the logical End-of-File string to eof_string.  The xargs command reads standard input until it encounters either an End-of-File character or the logical EOF string.  If you do not specify the -e flag, the default eof_string is _ (underline).  If you specify -e with no eof_string, xargs interprets the underline character as a literal character, rather than as an End-of-File marker. 

-i[replace_string]
Takes an entire line as a single argument and inserts it in each instance of replace_string found in the command string.  A maximum of five arguments in the command string can each contain one or more instances of replace_string.  The xargs command discards spaces and tabs at the beginning of each line.  The argument constructed cannot be larger than 255 bytes.  The default replace_string is {}.  This flag also turns on the -x flag. 

-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 flag turns on the -x flag. 

-nnumber
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] flag.  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. 

-pAsks 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.  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. 

-tEchoes the command string and each constructed argument list to file descriptor 2 (usually standard error). 

-xStops running xargs if any argument list is greater than the number of characters specified by the -slength flag.  This flag is turned on if you specify either the -i or -l flags.  If you do not specify -i, -l, or -n, the total length of all arguments must be within the length limit. 

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). 

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 filenames than fit on a single line, then xargs runs the lint command with the filenames that fit.  It then constructs and runs another lint command using the remaining filenames.  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 filenames.  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 filenames fit on one line. Do this by using xargs with the -x flag:

xargs  -x  lint  -a  <cfiles

If all the filenames 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 filenames, 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 filenames each (-n2):

diff  starting  chap1
diff  concepts  chap2
diff  writing  chap3

The -t flag 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 reference page.) 

     3.To insert filenames 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 flag 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. 

RELATED INFORMATION

Commands:  sh(1).