shell_cmds-207.11.1.tar.gz

[apple/shell_cmds.git] / xargs / xargs.1

diff --git a/xargs/xargs.1 b/xargs/xargs.1
index 9db9a3f2f381fc29aaf35d4173693a012fe94404..90551f98a3d6a76b6e793dd6edeb469c51551a09 100644 (file)
--- a/xargs/xargs.1
+++ b/xargs/xargs.1
@@ -34,10 +34,10 @@
 .\" 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 2, 2004
 .Dt XARGS 1
 .Os
 .Sh NAME
@@ -45,7 +45,7 @@
 .Nd "construct argument list(s) and execute utility"
 .Sh SYNOPSIS
 .Nm
-.Op Fl 0pt
+.Op Fl 0opt
 .Op Fl E Ar eofstr
 .Oo
 .Fl I Ar replstr
@@ -57,24 +57,24 @@
 .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
+from the standard input of
+.Nm .
+The utility
 is repeatedly executed until standard input is exhausted.
 .Pp
 Spaces, tabs and newlines may be embedded in arguments using single
@@ -105,7 +105,7 @@ as a logical EOF marker.
 .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
@@ -136,7 +136,7 @@ If this option is specified,
 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
@@ -167,15 +167,22 @@ 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
@@ -191,6 +198,19 @@ arguments remaining for the last invocation of
 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.
 .It Fl p
 Echo each command to be executed and ask the user whether it should be
 executed.
@@ -204,6 +224,9 @@ No commands are executed if the process is not attached to a terminal.
 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
 Set the maximum number of bytes for the command line length provided to
 .Ar utility .
@@ -229,9 +252,9 @@ to terminate immediately if a command line containing
 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
@@ -244,9 +267,26 @@ The
 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.
+.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.
@@ -265,7 +305,8 @@ exits with a value of 1.
 .Sh SEE ALSO
 .Xr echo 1 ,
 .Xr find 1 ,
-.Xr execvp 3
+.Xr execvp 3 ,
+.Xr compat 5
 .Sh STANDARDS
 The
 .Nm
@@ -273,7 +314,7 @@ utility is expected to be
 .St -p1003.2
 compliant.
 The
-.Fl J
+.Fl J , o , P
 and
 .Fl R
 options are non-standard
@@ -291,3 +332,12 @@ size of the environment is increased, it risks
 .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.