xargs(1)						      General Commands Manual							  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] [argu-
       ment...]

       The xargs command constructs a command line by combining a command string, containing a command and its options or  arguments,  with  addi-
       tional 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

       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.  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.  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 com-
       mand 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.  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.	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.	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.  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.  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 com-
       mand string.  Any other response causes xargs to skip that particular invocation of the command string.	You are asked about  each  invoca-
       tion.   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.	Echoes the command string and each constructed argument list to file descriptor 2 (usually standard error).  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

       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.  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: All invocations of CommandString returned exit status zero.  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.  The command specified by CommandString was found but could not be invoked.  The command specified by CommandString could not	be
       found.

EXAMPLES

       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.	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 argu-
	      ments 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.)  To insert file namess into the middle of com-
	      mands, use a command line similar to the following: ls  |  xargs	-t  -i	mv  {}	{}.old

	      This renames all files in the current directory by adding 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 con-
	      structs the following commands:

	      mv  chap1  chap1.old mv  chap2  chap2.old mv  chap3  chap3.old 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: 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 vari-
       ables  contain  an  invalid setting, the utility behaves as if none of the variables had been defined.  If set to a non-empty string value,
       overrides the values of all the other internationalization variables.  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.  Determines the locale for the format and contents of diagnos-
       tic  messages  written to standard error.  Determines the location of message catalogues for the processing of LC_MESSAGES.  Determines the
       location of CommandString.

SEE ALSO

       Commands:  ksh(1), Bourne shell sh(1b), POSIX shell sh(1p)

       Standards:  standards(5)

																	  xargs(1)