X-Git-Url: https://git.saurik.com/apple/shell_cmds.git/blobdiff_plain/c0fcf4e10b938344ef61467570bddfdc19cc8b7b..9bafe2801c85cb98680afa22c908a5f5f018b3aa:/xargs/xargs.1 diff --git a/xargs/xargs.1 b/xargs/xargs.1 index cdff51a..9db9a3f 100644 --- a/xargs/xargs.1 +++ b/xargs/xargs.1 @@ -1,5 +1,3 @@ -.\" $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. .\" @@ -36,8 +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 $ +.\" $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 @@ -45,13 +45,20 @@ .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 @@ -80,15 +87,92 @@ up to the matching double quote. 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. @@ -107,19 +191,33 @@ arguments remaining for the last invocation of 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. @@ -149,44 +247,47 @@ command line cannot be assembled, 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 .