.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\" must display the following acknowledgement:
-.\" This product includes software developed by the University of
-.\" California, Berkeley and its contributors.
-.\" 4. Neither the name of the University nor the names of its contributors
+.\" 3. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" 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 $
+.\" $FreeBSD: src/usr.bin/xargs/xargs.1,v 1.34 2005/05/21 09:55:09 ru Exp $
.\" $xMach: xargs.1,v 1.2 2002/02/23 05:23:37 tim Exp $
.\"
-.Dd May 7, 2001
+.Dd August 4, 2015
.Dt XARGS 1
.Os
.Sh NAME
.Nd "construct argument list(s) and execute utility"
.Sh SYNOPSIS
.Nm
-.Op Fl 0pt
+.Op Fl 0oprt
.Op Fl E Ar eofstr
.Oo
.Fl I Ar replstr
.Op Fl R Ar replacements
+.Op Fl S Ar replsize
.Oc
.Op Fl J Ar replstr
.Op Fl L Ar number
.Fl n Ar number
.Op Fl x
.Oc
+.Op Fl P Ar maxprocs
.Op Fl s Ar size
.Op Ar utility Op Ar argument ...
.Sh DESCRIPTION
The
.Nm
-utility reads space, tab, newline and end-of-file delimited arguments
-from the standard input and executes the specified
+utility reads space, tab, newline and end-of-file delimited strings
+from the standard input and executes
.Ar utility
-with them as
+with the strings as
arguments.
.Pp
-The utility and any arguments specified on the command line are given
-to the
+Any arguments specified on the command line are given to
.Ar utility
upon each invocation, followed by some number of the arguments read
-from standard input.
-The
-.Ar utility
-is repeatedly executed until standard input is exhausted.
+from the standard input of
+.Nm .
+This is repeated until standard input is exhausted.
.Pp
Spaces, tabs and newlines may be embedded in arguments using single
(``\ '\ '')
.It Fl I Ar replstr
Execute
.Ar utility
-for each input line, replacing one or more occurences of
+for each input line, replacing one or more occurrences of
.Ar replstr
in up to
.Ar replacements
.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
+beyond
+.Ar replsize
+(or 255 if no
+.Fl S
+flag is specified)
+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
+up to
+.Ar replsize
+bytes.
+The size limit does not apply to arguments to
.Ar utility
which do not contain
.Ar replstr ,
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
+This option will not affect how many arguments will be read from input
.Pq Fl n ,
or the size of the command(s)
.Nm
directory to
.Pa destdir :
.Pp
-.Dl /bin/ls -1d [A-Z]* | xargs -J % cp -rp % 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
-lines read.
+non-empty lines read.
+A line ending with a space continues to the next non-empty line.
If EOF is reached and fewer lines have been read than
.Ar number
then
.Ar utility
will be called with the available lines.
+The
+.Fl L
+and
+.Fl n
+options are mutually-exclusive; the last one given will be used.
.It Fl n Ar number
Set the maximum number of arguments taken from standard input for each
-invocation of the utility.
+invocation of
+.Ar utility .
An invocation of
.Ar utility
will use less than
The current default value for
.Ar number
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.
+If
+.Ar maxprocs
+is set to 0,
+.Nm
+will run as many processes as possible.
.It Fl p
Echo each command to be executed and ask the user whether it should be
executed.
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
+Compatibility with GNU
+.Nm .
+The GNU version of
+.Nm
+runs the
+.Ar utility
+argument at least once, even if
+.Nm
+input is empty, and it supports a
+.Fl r
+option to inhibit this behavior.
+The
+.Fx
+version of
+.Nm
+does not run the
+.Ar utility
+argument on empty input, but it supports the
+.Fl r
+option for command-line compatibility with GNU
+.Nm ,
+but the
+.Fl r
+option does nothing in the
+.Fx
+version of
+.Nm .
.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 replsize
+Specify the amount of space (in bytes) that
+.Fl I
+can use for replacements.
+The default for
+.Ar replsize
+is 255.
.It Fl s Ar size
Set the maximum number of bytes for the command line length provided to
.Ar utility .
arguments will not fit in the specified (or default) command line length.
.El
.Pp
-If no
+If
.Ar utility
-is specified,
+is omitted,
.Xr echo 1
is used.
.Pp
utility exits immediately (without processing any further input) if a
command line cannot be assembled,
.Ar utility
-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
+cannot be invoked, an invocation of
+.Ar utility
+is terminated by a signal,
+or an invocation of
+.Ar utility
+exits with a value of 255, the
+.Nm
+utility stops processing input and exits after all invocations of
+.Ar utility
+finish processing.
+.Sh LEGACY DESCRIPTION
+In legacy mode, the
+.Fl L
+option treats all newlines as end-of-line, regardless of whether
+the line is empty or ends with a space.
+In addition, the
+.Fl L
+and
+.Fl n
+options are not mutually-exclusive.
+.Pp
+For more information about legacy mode, see
+.Xr compat 5 .
+.Sh EXIT STATUS
The
.Nm
utility exits with a value of 0 if no error occurs.
.Sh SEE ALSO
.Xr echo 1 ,
.Xr find 1 ,
-.Xr execvp 3
+.Xr execvp 3 ,
+.Xr compat 5
.Sh STANDARDS
The
.Nm
.St -p1003.2
compliant.
The
-.Fl J
+.Fl J , o , P, R
and
-.Fl R
+.Fl S
options are non-standard
.Fx
extensions which may not be available on other operating systems.
.Sh HISTORY
The
.Nm
-command appeared in PWB UNIX.
+utility appeared in PWB UNIX.
.Sh BUGS
If
.Ar utility
.Xr execvp 3
failing with
.Er E2BIG .
+.Pp
+The
+.Nm
+utility does not take multibyte characters into account when performing
+string comparisons for the
+.Fl I
+and
+.Fl J
+options, which may lead to incorrect results in some locales.
projects / apple / shell_cmds.git / blobdiff