1.\" $NetBSD: xargs.1,v 1.23 2012/10/13 14:18:17 njoly 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.40 2010/12/11 08:32:16 joel Exp $ 36.\" $xMach: xargs.1,v 1.2 2002/02/23 05:23:37 tim Exp $ 37.\" 38.Dd December 21, 2010 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 0oprt 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.It Fl L Ar number 170Call 171.Ar utility 172for every 173.Ar number 174lines read. 175If EOF is reached and fewer lines have been read than 176.Ar number 177then 178.Ar utility 179will be called with the available lines. 180.It Fl n Ar number 181Set the maximum number of arguments taken from standard input for each 182invocation of 183.Ar utility . 184An invocation of 185.Ar utility 186will use less than 187.Ar number 188standard input arguments if the number of bytes accumulated (see the 189.Fl s 190option) exceeds the specified 191.Ar size 192or there are fewer than 193.Ar number 194arguments remaining for the last invocation of 195.Ar utility . 196The current default value for 197.Ar number 198is 5000. 199.It Fl o 200Reopen stdin as 201.Pa /dev/tty 202in the child process before executing the command. 203This is useful if you want 204.Nm 205to run an interactive application. 206.It Fl P Ar maxprocs 207Parallel mode: run at most 208.Ar maxprocs 209invocations of 210.Ar utility 211at once. 212.It Fl p 213Echo each command to be executed and ask the user whether it should be 214executed. 215An affirmative response, 216.Ql y 217in the POSIX locale, 218causes the command to be executed, any other response causes it to be 219skipped. 220No commands are executed if the process is not attached to a terminal. 221.It Fl r 222Compatibility with GNU 223.Nm . 224The GNU version of 225.Nm 226runs the 227.Ar utility 228argument at least once, even if 229.Nm 230input is empty, and it supports a 231.Fl r 232option to inhibit this behavior. 233The 234.Nx 235version of 236.Nm 237does not run the 238.Ar utility 239argument on empty input, but it supports the 240.Fl r 241option for command-line compatibility with GNU 242.Nm ; 243but the 244.Fl r 245option does nothing in the 246.Nx 247version of 248.Nm . 249.It Fl R Ar replacements 250Specify the maximum number of arguments that 251.Fl I 252will do replacement in. 253If 254.Ar replacements 255is negative, the number of arguments in which to replace is unbounded. 256.It Fl S Ar replsize 257Specify the amount of space (in bytes) that 258.Fl I 259can use for replacements. 260The default for 261.Ar replsize 262is 255. 263.It Fl s Ar size 264Set the maximum number of bytes for the command line length provided to 265.Ar utility . 266The sum of the length of the utility name, the arguments passed to 267.Ar utility 268(including 269.Dv NULL 270terminators) and the current environment will be less than or equal to 271this number. 272The current default value for 273.Ar size 274is 275.Dv ARG_MAX 276- 4096. 277.It Fl t 278Echo the command to be executed to standard error immediately before it 279is executed. 280.It Fl x 281Force 282.Nm 283to terminate immediately if a command line containing 284.Ar number 285arguments will not fit in the specified (or default) command line length. 286.El 287.Pp 288If 289.Ar utility 290is omitted, 291.Xr echo 1 292is used. 293.Pp 294Undefined behavior may occur if 295.Ar utility 296reads from the standard input. 297.Pp 298The 299.Nm 300utility exits immediately (without processing any further input) if a 301command line cannot be assembled, 302.Ar utility 303cannot be invoked, an invocation of 304.Ar utility 305is terminated by a signal, 306or an invocation of 307.Ar utility 308exits with a value of 255. 309.Sh FILES 310.Bl -tag -width /dev/tty -compact 311.It Pa /dev/tty 312used to read responses in prompt mode 313.El 314.Sh EXIT STATUS 315.Nm 316exits with one of the following values: 317.Bl -tag -width Ds -compact 318.It 0 319All invocations of 320.Ar utility 321returned a zero exit status. 322.It 123 323One or more invocations of 324.Ar utility 325returned a nonzero exit status. 326.It 124 327The 328.Ar utility 329exited with a 255 exit status. 330.It 125 331The 332.Ar utility 333was killed or stopped by a signal. 334.It 126 335The 336.Ar utility 337was found but could not be invoked. 338.It 127 339The 340.Ar utility 341could not be found. 342.It 1 343Some other error occurred. 344.El 345.Sh SEE ALSO 346.Xr echo 1 , 347.Xr find 1 , 348.Xr execvp 3 349.Sh STANDARDS 350The 351.Nm 352utility is expected to be 353.St -p1003.2 354compliant. 355The 356.Fl J , o , P , R , 357and 358.Fl S 359options are non-standard 360.Fx 361extensions which may not be available on other operating systems. 362.Sh HISTORY 363The 364.Nm 365utility appeared in PWB UNIX 1.0. 366It made its first BSD appearance in the 4.3 Reno release. 367.Pp 368The meaning of 123, 124, and 125 exit values and the 369.Fl 0 370option were taken from GNU xargs. 371.Sh BUGS 372If 373.Ar utility 374attempts to invoke another command such that the number of arguments or the 375size of the environment is increased, it risks 376.Xr execvp 3 377failing with 378.Er E2BIG . 379.Pp 380The 381.Nm 382utility does not take multibyte characters into account when performing 383string comparisons for the 384.Fl I 385and 386.Fl J 387options, which may lead to incorrect results in some locales. 388