xargs(1)							     xargs(1)



NAME
  xargs - Constructs argument lists and runs commands

SYNOPSIS

  xargs [-e[EndOfFileString]] [-EEndOfFileString] [-i[ReplacementString]]
  [-IReplacementString] [-l[Number]] [-LNumber] [-n[Number]] [-ptrx]
  [-s[Length] [CommandString] [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 EndOfFileString
      Sets the logical End-of-File string to eof_string.  The xargs command
      reads standard input until it encounters either an End-of-File charac-
      ter 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 char-
      acter, rather than as an End-of-File marker.

  -E EndOfFileString
      Specifies a logical End-Of-File string to replace the default under-
      score.  The xargs command reads standard input until either End-Of-File
      or the logical EOF string is encountered.

  -i ReplacementString
      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.

  -I ReplacementString
      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 ReplacementString. Any blank characters at the
      beginning of each line are ignored. Constructed arguments cannot grow
      larger than 255 bytes. Flag -x is forced on. The -I and -i flags 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 con-
      tinuation through the next nonempty line.	 The default number is 1.
      This flag turns on the -x flag.

  -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 flags are mutually
      exclusive; the last one takes effect.

  -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 charac-
      ters 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 speci-
      fied by -s.

  -p  Asks whether or not to run the command string.  It displays the con-
      structed 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 -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 pro-
  cedure, 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 com-
       mand 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 con-
       tains 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	  to run the command.  Press  alone if you do not
       want to run it.

RELATED INFORMATION

  Commands:  sh(1).