home | help
XARGS(1)		     General Commands Manual			XARGS(1)

NAME
     xargs -- construct argument list(s) and execute utility

SYNOPSIS
     xargs [-0pt] [-E eofstr] [-I replstr [-R replacements]] [-J replstr]
	   [-L number] [-n number [-x]] [-s size] [utility [argument ...]]

DESCRIPTION
     The xargs utility reads space, tab, newline and end-of-file delimited argu-
     ments  from the standard input and executes the specified utility with them
     as arguments.

     The utility and any arguments specified on the command line  are  given  to
     the  utility upon each invocation, followed by some number of the arguments
     read from standard input.	The utility is repeatedly executed  until  stan-
     dard input is exhausted.

     Spaces,  tabs  and  newlines  may	be  embedded  in  arguments using single
     (`` ' '') or double (``"'') quotes or backslashes (``\'').   Single  quotes
     escape  all  non-single  quote  characters,  excluding  newlines, up to the
     matching single quote.  Double quotes escape all non-double  quote  charac-
     ters,  excluding  newlines,  up  to  the matching double quote.  Any single
     character, including newlines, may be escaped by a backslash.

     The options are as follows:

     -0      Change xargs to expect NUL (``\0'') characters as	separators,  in-
	     stead  of spaces and newlines.  This is expected to be used in con-
	     cert with the -print0 function in find(1).

     -E eofstr
	     Use eofstr as a logical EOF marker.

     -I replstr
	     Execute utility for each input line,  replacing  one  or  more  oc-
	     curences  of  replstr  in up to replacements (or 5 if no -R flag is
	     specified) arguments to utility with the entire line of input.  The
	     resulting arguments, after replacement is done, will not be allowed
	     to grow beyond 255 bytes; this is implemented by  concatenating  as
	     much  of  the  argument containing replstr as possible, to the con-
	     structed arguments to utility, up to 255 bytes.  The 255 byte limit
	     does not apply  to  arguments  to	utility  which	do  not  contain
	     replstr,  and  furthermore,  no replacement will be done on utility
	     itself.  Implies -x.

     -J replstr
	     If this option is specified, xargs will  use  the	data  read  from
	     standard  input  to replace the first occurrence of replstr instead
	     of appending that data after all other arguments.	This option will
	     not effect how many arguments will be read from input (-n), or  the
	     size  of  the command(s) xargs will generate (-s).  The option just
	     moves where those arguments will be placed in the	command(s)  that
	     are  executed.   The replstr must show up as a distinct argument to
	     xargs.  It will not be recognized if, for instance, it  is  in  the
	     middle  of a quoted string.  Furthermore, only the first occurrence
	     of the replstr will be replaced.  For example, the  following  com-
	     mand  will  copy the list of files and directories which start with
	     an uppercase letter in the current directory to destdir:

		   /bin/ls -1d [A-Z]* | xargs -J % cp -rp % destdir

     -L number
	     Call utility for every number lines read.	If EOF	is  reached  and
	     fewer  lines have been read than number then utility will be called
	     with the available lines.

     -n number
	     Set the maximum number of arguments taken from standard  input  for
	     each  invocation of the utility.  An invocation of utility will use
	     less than number standard input arguments if the  number  of  bytes
	     accumulated (see the -s option) exceeds the specified size or there
	     are  fewer  than number arguments remaining for the last invocation
	     of utility.  The current default value for number is 5000.

     -p      Echo each command to be executed and ask the user whether it should
	     be executed.  An affirmative response, `y'  in  the  POSIX  locale,
	     causes  the command to be executed, any other response causes it to
	     be skipped.  No commands are executed if the  process  is	not  at-
	     tached to a terminal.

     -R replacements
	     Specify the maximum number of arguments that -I will do replacement
	     in.

     -s size
	     Set  the  maximum	number of bytes for the command line length pro-
	     vided to utility.	The sum of the length of the utility  name,  the
	     arguments	passed	to  utility (including NULL terminators) and the
	     current environment will be less than or equal to this number.  The
	     current default value for size is ARG_MAX - 4096.

     -t      Echo the command to be executed to standard error	immediately  be-
	     fore it is executed.

     -x      Force  xargs  to terminate immediately if a command line containing
	     number arguments will not fit in the specified (or default) command
	     line length.

     If no utility is specified, echo(1) is used.

     Undefined behavior may occur if utility reads from the standard input.

     The xargs utility exits immediately (without processing any further  input)
     if  a command line cannot be assembled, utility cannot be invoked, an invo-
     cation of the utility is terminated by a signal or  an  invocation  of  the
     utility exits with a value of 255.

DIAGNOSTICS
     The  xargs  utility exits with a value of 0 if no error occurs.  If utility
     cannot be found, xargs exits with a value of 127, otherwise if utility can-
     not be executed, xargs exits with a value of 126.	If any other  error  oc-
     curs, xargs exits with a value of 1.

SEE ALSO
     echo(1), find(1), execvp(3)

STANDARDS
     The  xargs utility is expected to be IEEE Std 1003.2 ("POSIX.2") compliant.
     The -J and -R options are non-standard FreeBSD extensions which may not  be
     available on other operating systems.

HISTORY
     The xargs command appeared in PWB UNIX.

BUGS
     If utility attempts to invoke another command such that the number of argu-
     ments or the size of the environment is increased, it risks execvp(3) fail-
     ing with E2BIG.

FreeBSD 5.0			   May 7, 2001				XARGS(1)

home | help