[BACK]Return to xargs.1 CVS log [TXT][DIR] Up to [local] / src / usr.bin / xargs

Diff for /src/usr.bin/xargs/xargs.1 between version 1.11 and 1.12

version 1.11, 2003/06/03 02:56:24 version 1.12, 2003/06/12 01:09:23
Line 1 
Line 1 
 .\"     $OpenBSD$  .\"     $OpenBSD$
 .\"     $NetBSD: xargs.1,v 1.6 1994/11/14 06:51:40 jtc Exp $  .\"     $FreeBSD: xargs.1,v 1.30 2003/05/21 21:07:28 ru Exp $$
 .\"  .\"
 .\" Copyright (c) 1990, 1991, 1993  .\" Copyright (c) 1990, 1991, 1993
 .\"     The Regents of the University of California.  All rights reserved.  .\"     The Regents of the University of California.  All rights reserved.
Line 34 
Line 34 
 .\"  .\"
 .\"     @(#)xargs.1     8.1 (Berkeley) 6/6/93  .\"     @(#)xargs.1     8.1 (Berkeley) 6/6/93
 .\"  .\"
 .Dd June 6, 1993  .Dd May 7, 2001
 .Dt XARGS 1  .Dt XARGS 1
 .Os  .Os
 .Sh NAME  .Sh NAME
 .Nm xargs  .Nm xargs
 .Nd "construct argument list(s) and execute utility"  .Nd "construct argument list(s) and execute utility"
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .Nm xargs  .Nm
 .Op Fl 0  .Op Fl 0opt
 .Op Fl t  .Op Fl E Ar eofstr
 .Oo Op Fl x  .Oo
   .Fl I Ar replstr
   .Op Fl R Ar replacements
   .Oc
   .Op Fl J Ar replstr
   .Op Fl L Ar number
   .Oo
 .Fl n Ar number  .Fl n Ar number
   .Op Fl x
 .Oc  .Oc
   .Op Fl P Ar maxjobs
 .Op Fl s Ar size  .Op Fl s Ar size
 .Op Ar utility Op Ar arguments ...  .Op Ar utility Op Ar argument ...
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm  .Nm
 utility reads space, tab, newline, and end-of-file delimited arguments  utility reads space, tab, newline, and end-of-file delimited strings
 from the standard input and executes the specified  from the standard input and executes the specified
 .Ar utility  .Ar utility
 with them as  with the strings as
 arguments.  arguments.
 .Pp  .Pp
 The utility and any arguments specified on the command line are given  Any arguments specified on the command line are given to the
 to the  
 .Ar utility  .Ar utility
 upon each invocation, followed by some number of the arguments read  upon each invocation, followed by some number of the arguments read
 from standard input.  from standard input.
Line 82 
Line 89 
 The options are as follows:  The options are as follows:
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Fl 0  .It Fl 0
 Changes  Change
 .Nm  .Nm
 to expect NUL  to expect NUL
 .Pq Ql \e0  .Pq Ql \e0
Line 91 
Line 98 
 .Fl print0  .Fl print0
 function in  function in
 .Xr find 1 .  .Xr find 1 .
   .It Fl E Ar eofstr
   Use
   .Ar eofstr
   as a logical EOF marker.
   .It Fl I Ar replstr
   Execute
   .Ar utility
   for each input line, replacing one or more occurrences of
   .Ar replstr
   in up to
   .Ar replacements
   (or 5 if no
   .Fl R
   flag is specified) arguments to
   .Ar 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
   .Ar replstr
   as possible, to the constructed arguments to
   .Ar utility ,
   up to 255 bytes.
   The 255 byte limit does not apply to arguments to
   .Ar utility
   which do not contain
   .Ar replstr ,
   and furthermore, no replacement will be done on
   .Ar utility
   itself.
   Implies
   .Fl x .
   .It Fl J Ar replstr
   If this option is specified,
   .Nm
   will use the data read from standard input to replace the first occurrence of
   .Ar replstr
   instead of appending that data after all other arguments.
   This option will not effect how many arguments will be read from input
   .Pq Fl n ,
   or the size of the command(s)
   .Nm
   will generate
   .Pq Fl s .
   The option just moves where those arguments will be placed in the command(s)
   that are executed.
   The
   .Ar replstr
   must show up as a distinct
   .Ar argument
   to
   .Nm 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
   .Ar replstr
   will be replaced.
   For example, the following command will copy the list of files and
   directories which start with an uppercase letter in the current
   directory to
   .Pa destdir :
   .Pp
   .Dl /bin/ls -1d [A-Z]* | xargs -J % cp -rp % destdir
   .It Fl L Ar number
   Call
   .Ar utility
   for every
   .Ar number
   of lines read.
   If EOF is reached and fewer than
   .Ar number
   lines have been read then
   .Ar utility
   will be called with the available lines.
 .It Fl n Ar number  .It Fl n Ar number
 Set the maximum number of arguments taken from standard input for each  Set the maximum number of arguments taken from standard input for each
 invocation of the utility.  invocation of
   .Ar utility .
 An invocation of  An invocation of
 .Ar utility  .Ar utility
 will use less than  will use less than
Line 109 
Line 191 
 The current default value for  The current default value for
 .Ar number  .Ar number
 is 5000.  is 5000.
   .It Fl o
   Reopen stdin as
   .Pa /dev/tty
   in the child process before executing the command.
   This is useful if you want
   .Nm
   to run an interactive application.
   .It Fl P Ar maxprocs
   Parallel mode: run at most
   .Ar maxprocs
   invocations of
   .Ar utility
   at once.
   .It Fl p
   Echo each command to be executed and ask the user whether it should be
   executed.
   An affirmative response,
   .Ql 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 attached to a terminal.
   .It Fl R Ar replacements
   Specify the maximum number of arguments that
   .Fl I
   will do replacement in.
   If
   .Ar replacements
   is negative, the number of arguments in which to replace is unbounded.
 .It Fl s Ar size  .It Fl s Ar size
 Set the maximum number of bytes for the command-line length provided to  Set the maximum number of bytes for the command line length provided to
 .Ar utility .  .Ar utility .
 The sum of the length of the utility name and the arguments passed to  The sum of the length of the utility name, the arguments passed to
 .Ar utility  .Ar utility
 (including null terminators) will be less than or equal to this number.  (including
   .Dv NUL
   terminators) and the current environment will be less than or equal to
   this number.
 The current default value for  The current default value for
 .Ar size  .Ar size
 is  is
Line 128 
Line 242 
 .Nm  .Nm
 to terminate immediately if a command line containing  to terminate immediately if a command line containing
 .Ar number  .Ar number
 arguments will not fit in the specified (or default) command-line length.  arguments will not fit in the specified (or default) command line length.
 .El  .El
 .Pp  .Pp
 If no  If no
Line 146 
Line 260 
 utility exits immediately (without processing any further input) if a  utility exits immediately (without processing any further input) if a
 command line cannot be assembled,  command line cannot be assembled,
 .Ar utility  .Ar utility
 cannot be invoked, an invocation of the utility is terminated by a signal,  cannot be invoked, an invocation of
 or an invocation of the utility exits with a value of 255.  .Ar utility
 .Pp  is terminated by a signal,
   or an invocation of
   .Ar utility
   exits with a value of 255.
   .Sh DIAGNOSTICS
 .Nm  .Nm
 exits with one of the following values:  exits with one of the following values:
 .Pp  .Pp
Line 172 
Line 290 
 .It 126  .It 126
 The  The
 .Ar utility  .Ar utility
 was found but could not be invoked.  was found but could not be executed.
 .It 127  .It 127
 The  The
 .Ar utility  .Ar utility
Line 182 
Line 300 
 .El  .El
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr echo 1 ,  .Xr echo 1 ,
 .Xr find 1  .Xr find 1 ,
   .Xr execvp 3
 .Sh STANDARDS  .Sh STANDARDS
 The  The
 .Nm  .Nm
 utility is expected to be  utility is expected to be
 .St -p1003.2  .St -p1003.2
 compliant.  compliant.
 .Sh HISTORY  The
 The meaning of 123, 124, and 125 exit values were taken from GNU  .Fl J , o , P
   and
   .Fl R
   options are non-standard
   extensions which may not be available on other operating systems.
   .Pp
   The meanings of the 123, 124, and 125 exit values were taken from
   .Tn GNU
 .Nm xargs .  .Nm xargs .
   .Sh HISTORY
   The
   .Nm
   command appeared in PWB UNIX.
   .Sh BUGS
   If
   .Ar utility
   attempts to invoke another command such that the number of arguments or the
   size of the environment is increased, it risks
   .Xr execvp 3
   failing with
   .Er E2BIG .
Legend:
Removed from v.1.11  
changed lines
  Added in v.1.12