-.\" $NetBSD: xargs.1,v 1.7 1997/06/24 00:45:28 lukem Exp $
-.\"
.\" Copyright (c) 1990, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" SUCH DAMAGE.
.\"
.\" @(#)xargs.1 8.1 (Berkeley) 6/6/93
+.\" $FreeBSD: src/usr.bin/xargs/xargs.1,v 1.23 2002/06/22 12:47:56 jmallett Exp $
+.\" $xMach: xargs.1,v 1.2 2002/02/23 05:23:37 tim Exp $
.\"
-.Dd June 6, 1993
+.Dd May 7, 2001
.Dt XARGS 1
.Os
.Sh NAME
.Nd "construct argument list(s) and execute utility"
.Sh SYNOPSIS
.Nm
-.Op Fl 0
-.Op Fl t
-.Oo Op Fl x
+.Op Fl 0pt
+.Op Fl E Ar eofstr
+.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
+.Op Fl x
.Oc
.Op Fl s Ar size
-.Op Ar utility Op Ar arguments ...
+.Op Ar utility Op Ar argument ...
.Sh DESCRIPTION
The
.Nm
Any single character, including newlines, may be escaped by a backslash.
.Pp
The options are as follows:
-.Bl -tag -width Fl
+.Bl -tag -width indent
.It Fl 0
-Use NUL
-(``\e0'')
-instead of whitespace as the argument separator.
-This can be used in conjuction with the
+Change
+.Nm
+to expect NUL
+(``\\0'')
+characters as separators, instead of spaces and newlines.
+This is expected to be used in concert with the
.Fl print0
-option of
+function in
.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 occurences 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 .
+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
+.Pp
+.It Fl L Ar number
+Call
+.Ar utility
+for every
+.Ar number
+lines read.
+If EOF is reached and fewer lines have been read than
+.Ar number
+then
+.Ar utility
+will be called with the available lines.
.It Fl n Ar number
Set the maximum number of arguments taken from standard input for each
invocation of the utility.
The current default value for
.Ar number
is 5000.
+.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.
.It Fl s Ar size
Set the maximum number of bytes for the command line length provided to
.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
(including
.Dv NULL
-terminators) will be less than or equal to this number.
+terminators) and the current environment will be less than or equal to
+this number.
The current default value for
.Ar size
is
.Dv ARG_MAX
-- 2048.
+- 4096.
.It Fl t
Echo the command to be executed to standard error immediately before it
is executed.
cannot be invoked, an invocation of the utility is terminated by a signal
or an invocation of the utility exits with a value of 255.
.Sh DIAGNOSTICS
-.Nm
-exits with one of the following values:
-.Bl -tag -width Ds -compact
-.It 0
-All invocations of
-.Ar utility
-returned a zero exit status.
-.It 123
-One or more invocations of
-.Ar utility
-returned a nonzero exit status.
-.It 124
-The
-.Ar utility
-exited with a 255 exit status.
-.It 125
-The
-.Ar utility
-was killed or stopped by a signal.
-.It 126
The
+.Nm
+utility exits with a value of 0 if no error occurs.
+If
.Ar utility
-was found but could not be invoked.
-.It 127
-The
+cannot be found,
+.Nm
+exits with a value of 127, otherwise if
.Ar utility
-could not be found.
-.It 1
-Some other error occurred.
-.El
+cannot be executed,
+.Nm
+exits with a value of 126.
+If any other error occurs,
+.Nm
+exits with a value of 1.
.Sh SEE ALSO
.Xr echo 1 ,
-.Xr find 1
+.Xr find 1 ,
+.Xr execvp 3
.Sh STANDARDS
The
.Nm
utility is expected to be
.St -p1003.2
compliant.
+The
+.Fl J
+and
+.Fl R
+options are non-standard
+.Fx
+extensions which may not be available on other operating systems.
.Sh HISTORY
-The meaning of 123, 124, and 125 exit values were taken from GNU xargs.
+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 .
projects / apple / shell_cmds.git / blobdiff