1.\" $NetBSD: xargs.1,v 1.20 2007/12/02 19:47:56 wiz Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" John B. Roll Jr. and the Institute of Electrical and Electronics 8.\" Engineers, Inc. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)xargs.1 8.1 (Berkeley) 6/6/93 35.\" $FreeBSD: src/usr.bin/xargs/xargs.1,v 1.37 2006/09/29 15:20:48 ru Exp $ 36.\" $xMach: xargs.1,v 1.2 2002/02/23 05:23:37 tim Exp $ 37.\" 38.Dd April 18, 2007 39.Dt XARGS 1 40.Os 41.Sh NAME 42.Nm xargs 43.Nd "construct argument list(s) and execute utility" 44.Sh SYNOPSIS 45.Nm 46.Op Fl 0opt 47.Op Fl E Ar eofstr 48.Oo 49.Fl I Ar replstr 50.Op Fl R Ar replacements 51.Op Fl S Ar replsize 52.Oc 53.Op Fl J Ar replstr 54.Op Fl L Ar number 55.Oo 56.Fl n Ar number 57.Op Fl x 58.Oc 59.Op Fl P Ar maxprocs 60.Op Fl s Ar size 61.Op Ar utility Op Ar argument ... 62.Sh DESCRIPTION 63The 64.Nm 65utility reads space, tab, newline and end-of-file delimited strings 66from the standard input and executes 67.Ar utility 68with the strings as 69arguments. 70.Pp 71Any arguments specified on the command line are given to 72.Ar utility 73upon each invocation, followed by some number of the arguments read 74from the standard input of 75.Nm . 76This is repeated until standard input is exhausted. 77.Pp 78Spaces, tabs and newlines may be embedded in arguments using single 79(``\ '\ '') 80or double (``"'') quotes or backslashes (``\e''). 81Single quotes escape all non-single quote characters, excluding newlines, 82up to the matching single quote. 83Double quotes escape all non-double quote characters, excluding newlines, 84up to the matching double quote. 85Any single character, including newlines, may be escaped by a backslash. 86.Pp 87The options are as follows: 88.Bl -tag -width indent 89.It Fl 0 90Change 91.Nm 92to expect NUL 93(``\e0'') 94characters as separators, instead of spaces and newlines. 95This is expected to be used in concert with the 96.Fl print0 97function in 98.Xr find 1 . 99.It Fl E Ar eofstr 100Use 101.Ar eofstr 102as a logical EOF marker. 103.It Fl I Ar replstr 104Execute 105.Ar utility 106for each input line, replacing one or more occurrences of 107.Ar replstr 108in up to 109.Ar replacements 110(or 5 if no 111.Fl R 112flag is specified) arguments to 113.Ar utility 114with the entire line of input. 115The resulting arguments, after replacement is done, will not be allowed to grow 116beyond 117.Ar replsize 118(or 255 if no 119.Fl S 120flag is specified) 121bytes; this is implemented by concatenating as much of the argument 122containing 123.Ar replstr 124as possible, to the constructed arguments to 125.Ar utility , 126up to 127.Ar replsize 128bytes. 129The size limit does not apply to arguments to 130.Ar utility 131which do not contain 132.Ar replstr , 133and furthermore, no replacement will be done on 134.Ar utility 135itself. 136Implies 137.Fl x . 138.It Fl J Ar replstr 139If this option is specified, 140.Nm 141will use the data read from standard input to replace the first occurrence of 142.Ar replstr 143instead of appending that data after all other arguments. 144This option will not affect how many arguments will be read from input 145.Pq Fl n , 146or the size of the command(s) 147.Nm 148will generate 149.Pq Fl s . 150The option just moves where those arguments will be placed in the command(s) 151that are executed. 152The 153.Ar replstr 154must show up as a distinct 155.Ar argument 156to 157.Nm . 158It will not be recognized if, for instance, it is in the middle of a 159quoted string. 160Furthermore, only the first occurrence of the 161.Ar replstr 162will be replaced. 163For example, the following command will copy the list of files and 164directories which start with an uppercase letter in the current 165directory to 166.Pa destdir : 167.Pp 168.Dl /bin/ls -1d [A-Z]* | xargs -J % cp -rp % destdir 169.Pp 170.It Fl L Ar number 171Call 172.Ar utility 173for every 174.Ar number 175lines read. 176If EOF is reached and fewer lines have been read than 177.Ar number 178then 179.Ar utility 180will be called with the available lines. 181.It Fl n Ar number 182Set the maximum number of arguments taken from standard input for each 183invocation of 184.Ar utility . 185An invocation of 186.Ar utility 187will use less than 188.Ar number 189standard input arguments if the number of bytes accumulated (see the 190.Fl s 191option) exceeds the specified 192.Ar size 193or there are fewer than 194.Ar number 195arguments remaining for the last invocation of 196.Ar utility . 197The current default value for 198.Ar number 199is 5000. 200.It Fl o 201Reopen stdin as 202.Pa /dev/tty 203in the child process before executing the command. 204This is useful if you want 205.Nm 206to run an interactive application. 207.It Fl P Ar maxprocs 208Parallel mode: run at most 209.Ar maxprocs 210invocations of 211.Ar utility 212at once. 213.It Fl p 214Echo each command to be executed and ask the user whether it should be 215executed. 216An affirmative response, 217.Ql y 218in the POSIX locale, 219causes the command to be executed, any other response causes it to be 220skipped. 221No commands are executed if the process is not attached to a terminal. 222.It Fl R Ar replacements 223Specify the maximum number of arguments that 224.Fl I 225will do replacement in. 226If 227.Ar replacements 228is negative, the number of arguments in which to replace is unbounded. 229.It Fl S Ar replsize 230Specify the amount of space (in bytes) that 231.Fl I 232can use for replacements. 233The default for 234.Ar replsize 235is 255. 236.It Fl s Ar size 237Set the maximum number of bytes for the command line length provided to 238.Ar utility . 239The sum of the length of the utility name, the arguments passed to 240.Ar utility 241(including 242.Dv NULL 243terminators) and the current environment will be less than or equal to 244this number. 245The current default value for 246.Ar size 247is 248.Dv ARG_MAX 249- 4096. 250.It Fl t 251Echo the command to be executed to standard error immediately before it 252is executed. 253.It Fl x 254Force 255.Nm 256to terminate immediately if a command line containing 257.Ar number 258arguments will not fit in the specified (or default) command line length. 259.El 260.Pp 261If 262.Ar utility 263is omitted, 264.Xr echo 1 265is used. 266.Pp 267Undefined behavior may occur if 268.Ar utility 269reads from the standard input. 270.Pp 271The 272.Nm 273utility exits immediately (without processing any further input) if a 274command line cannot be assembled, 275.Ar utility 276cannot be invoked, an invocation of 277.Ar utility 278is terminated by a signal, 279or an invocation of 280.Ar utility 281exits with a value of 255. 282.Sh EXIT STATUS 283.Nm 284exits with one of the following values: 285.Bl -tag -width Ds -compact 286.It 0 287All invocations of 288.Ar utility 289returned a zero exit status. 290.It 123 291One or more invocations of 292.Ar utility 293returned a nonzero exit status. 294.It 124 295The 296.Ar utility 297exited with a 255 exit status. 298.It 125 299The 300.Ar utility 301was killed or stopped by a signal. 302.It 126 303The 304.Ar utility 305was found but could not be invoked. 306.It 127 307The 308.Ar utility 309could not be found. 310.It 1 311Some other error occurred. 312.El 313.Sh FILES 314.Bl -tag -width /dev/tty -compact 315.It Pa /dev/tty 316used to read responses in prompt mode 317.El 318.Sh SEE ALSO 319.Xr echo 1 , 320.Xr find 1 , 321.Xr execvp 3 322.Sh STANDARDS 323The 324.Nm 325utility is expected to be 326.St -p1003.2 327compliant. 328The 329.Fl J , o , P , R , 330and 331.Fl S 332options are non-standard 333.Fx 334extensions which may not be available on other operating systems. 335.Sh HISTORY 336The 337.Nm 338utility appeared in PWB UNIX 1.0. 339It made its first BSD appearance in the 4.3 Reno release. 340.Pp 341The meaning of 123, 124, and 125 exit values and the 342.Fl 0 343option were taken from GNU xargs. 344.Sh BUGS 345If 346.Ar utility 347attempts to invoke another command such that the number of arguments or the 348size of the environment is increased, it risks 349.Xr execvp 3 350failing with 351.Er E2BIG . 352.Pp 353The 354.Nm 355utility does not take multibyte characters into account when performing 356string comparisons for the 357.Fl I 358and 359.Fl J 360options, which may lead to incorrect results in some locales. 361