XARGS(1)                                               XARGS(1)





NAME
       xargs  -  build  and execute command lines from standard
       input

SYNOPSIS
       xargs [-0prtx] [-E[eof-str]] [-e[eof-str]]  [--eof[=eof-
       str]]   [--null]   [-I[replace-str]]   [-i[replace-str]]
       [--replace[=replace-str]]    [-l[max-lines]]    [-L[max-
       lines]]    [--max-lines[=max-lines]]    [-n    max-args]
       [--max-args=max-args] [-s  max-chars]  [--max-chars=max-
       chars]  [-P max-procs] [--max-procs=max-procs] [--inter-
       active]   [--verbose]    [--exit]    [--no-run-if-empty]
       [--arg-file=file]  [--version]  [--help]  [command [ini-
       tial-arguments]]

DESCRIPTION
       This manual page documents the  GNU  version  of  xargs.
       xargs  reads items from the standard input, delimited by
       blanks (which can be protected  with  double  or  single
       quotes  or  a  backslash)  or newlines, and executes the
       command (default is /bin/echo) one or  more  times  with
       any  initial-arguments followed by items read from stan-
       dard input.  Blank  lines  on  the  standard  input  are
       ignored.

       Because  Unix filenames can contain blanks and newlines,
       this default behaviour is often  problematic;  filenames
       containing  blanks  and/or newlines are incorrectly pro-
       cessed by xargs.  In these situations it  is  better  to
       use  the  `-0'  option,  which  prevents  such problems.
       When using this option you will need to ensure that  the
       program  which  produces the input for xargs also uses a
       null character as a separator.  If that program  is  GNU
       find  for  example,  the  `-print0' option does this for
       you.

       If any invocation of the command exits with a status  of
       255,  xargs  will  stop  immediately without reading any
       further input.  An error message  is  issued  on  stderr
       when this happens.

   OPTIONS
       --arg-file=file, -a file
              Read  items  from file instead of standard input.
              If you use this option, stdin  remains  unchanged
              when commands are run.  Otherwise, stdin is redi-
              rected from /dev/null.


       --null, -0
              Input items are terminated by  a  null  character
              instead  of  by  whitespace,  and  the quotes and
              backslash are not  special  (every  character  is
              taken  literally).   Disables  the  end  of  file
              string, which is treated like any other argument.
              Useful  when  input  items  might  contain  white
              space, quote marks, or backslashes.  The GNU find
              -print0  option  produces input suitable for this
              mode.

       --eof[=eof-str], -E[eof-str]
              Set the end of file string to  eof-str.   If  the
              end of file string occurs as a line of input, the
              rest of the input  is  ignored.   If  eof-str  is
              omitted, there is no end of file string.  If this
              option is not given, no end  of  file  string  is
              used.

       -e[eof-str]
              This  option  is  a  synonym for the `-E' option.
              Use `-E' instead, because it is  POSIX  compliant
              while this option is not.

       --help Print a summary of the options to xargs and exit.

       --replace[=replace-str], -i[replace-str]
              Replace occurences of replace-str in the initial-
              arguments  with  names  read from standard input.
              Also, unquoted  blanks  do  not  terminate  input
              items; instead the separator is the newline char-
              acter.  If replace-str is omitted, it defaults to
              "{}"  (like for `find -exec').  Implies -x and -l
              1.

       --max-lines[=max-lines], -L[max-lines]
              Use at most max-lines nonblank  input  lines  per
              command line; max-lines defaults to 1 if omitted.
              Trailing blanks cause an input line to  be  logi-
              cally  continued on the next input line.  Implies
              -x.

       -l[max-lines]
              Deprecated; non-POSIX-compliant synonym  for  the
              -L option.

       --max-args=max-args, -n max-args
              Use  at most max-args arguments per command line.
              Fewer than max-args arguments will be used if the
              size  (see the -s option) is exceeded, unless the
              -x option is given,  in  which  case  xargs  will
              exit.

       --interactive, -p
              Prompt the user about whether to run each command
              line and read a line from the terminal.  Only run
              the  command line if the response starts with `y'
              or `Y'.  Implies -t.

       --no-run-if-empty, -r
              If the standard input does not contain  any  non-
              blanks,  do  not  run the command.  Normally, the
              command is run once even if there  is  no  input.
              This option is a GNU extension.

       --max-chars=max-chars, -s max-chars
              Use  at  most  max-chars  characters  per command
              line, including the command and initial-arguments
              and  the  terminating  nulls  at  the ends of the
              argument strings.  The default is 131072  charac-
              ters,  not  including the size of the environment
              variables (which are provided for  separately  so
              that  it doesn't matter if your environment vari-
              ables take up more than 131072 bytes).  The oper-
              ating system places limits on the values that you
              can usefully specify, and if you exceed  these  a
              warning message is printed and the value actually
              used is set to the  appropriate  upper  or  lower
              limit.

       --verbose, -t
              Print the command line on the standard error out-
              put before executing it.

       --version
              Print the version number of xargs and exit.

       --exit, -x
              Exit if the size (see the -s option) is exceeded.

       --max-procs=max-procs, -P max-procs
              Run  up  to  max-procs  processes  at a time; the
              default is 1.  If max-procs is 0, xargs will  run
              as many processes as possible at a time.  Use the
              -n option with -P;  otherwise  chances  are  that
              only one exec will be done.

EXAMPLES
       find /tmp -name core -type f -print | xargs /bin/rm -f

       Find files named core in or below the directory /tmp and
       delete them.  Note that this will  work  incorrectly  if
       there are any filenames containing newlines or spaces.

       find  /tmp -name core -type f -print0 | xargs -0 /bin/rm
       -f

       Find files named core in or below the directory /tmp and
       delete  them,  processing  filenames  in such a way that
       file or directory names containing  spaces  or  newlines
       are correctly handled.

       cut -d: -f1 < /etc/passwd | sort | xargs echo

       Generates a compact listing of all the users on the sys-
       tem.

EXIT STATUS
       xargs exits with the following status:
       0 if it succeeds
       123 if any invocation of the command exited with status 1-125
       124 if the command exited with status 255
       125 if the command is killed by a signal
       126 if the command cannot be run
       127 if the command is not found
       1 if some other error occurred.

       Exit codes greater than 128 are used  by  the  shell  to
       indicate that a program died due to a fatal signal.

STANDARDS CONFORMANCE
       As  of GNU xargs version 4.2.9, the default behaviour of
       xargs is not  to  have  a  logical  end-of-file  marker.
       POSIX (IEEE Std 1003.1, 2004 Edition) allows this.


SEE ALSO
       find(1),  locate(1),  locatedb(5),  updatedb(1), Finding
       Files (on-line in Info, or printed)

BUGS
       It is not possible for xargs to be used securely,  since
       there  will  always be a time gap between the production
       of the list of input files and their use in the commands
       that  xargs  issues.   If other users have access to the
       system, they can manipulate the filesystem  during  this
       time  window  to  force the action of the commands xargs
       runs to apply to files that you didn't  intend.   For  a
       more  detailed  discussion of this and related problems,
       please refer to the ``Security Considerations''  chapter
       in  the  findutils  Texinfo documentation.  The -execdir
       option of find can often be used as a more secure alter-
       native.

       When  you  use  the  -i  option, each line read from the
       input is buffered internally.   This means that there is
       an  upper  limit  on the length of input line that xargs
       will accept when used  with  the  -i  option.   To  work
       around  this  limitation,  you  can use the -s option to
       increase the amount of buffer space that xargs uses, and
       you  can also use an extra invocation of xargs to ensure
       that very long lines do not occur.  For example:

       somecommand | xargs -s 50000 echo | xargs -i  -s  100000
       rm '{}'

       Here,  the  first  invocation of xargs has no input line
       length limit because it doesn't use the -i option.   The
       second  invocation  of xargs does have such a limit, but
       we have ensured that the  it  never  encounters  a  line
       which  is  longer  than  it can handle.   This is not an
       ideal solution.   Instead,  the  -i  option  should  not
       impose a line length limit, which is why this discussion
       appears in the BUGS section.  The problem doesn't  occur
       with  the  output  of  find(1) because it emits just one
       filename per line.

       The best way to report a bug  is  to  use  the  form  at
       http://savannah.gnu.org/bugs/?group=findutils.  The rea-
       son for this is that you will  then  be  able  to  track
       progress  in  fixing the problem.   Other comments about
       xargs(1) and about the findutils package in general  can
       be  sent to the bug-findutils mailing list.  To join the
       list, send email to bug-findutils-request@gnu.org.



                                                       XARGS(1)
