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