1.\" $NetBSD: xargs.1,v 1.22 2010/12/22 09:05:07 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.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.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 223Compatibility with GNU 224.Nm . 225The GNU version of 226.Nm 227runs the 228.Ar utility 229argument at least once, even if 230.Nm 231input is empty, and it supports a 232.Fl r 233option to inhibit this behavior. 234The 235.Nx 236version of 237.Nm 238does not run the 239.Ar utility 240argument on empty input, but it supports the 241.Fl r 242option for command-line compatibility with GNU 243.Nm ; 244but the 245.Fl r 246option does nothing in the 247.Nx 248version of 249.Nm . 250.It Fl R Ar replacements 251Specify the maximum number of arguments that 252.Fl I 253will do replacement in. 254If 255.Ar replacements 256is negative, the number of arguments in which to replace is unbounded. 257.It Fl S Ar replsize 258Specify the amount of space (in bytes) that 259.Fl I 260can use for replacements. 261The default for 262.Ar replsize 263is 255. 264.It Fl s Ar size 265Set the maximum number of bytes for the command line length provided to 266.Ar utility . 267The sum of the length of the utility name, the arguments passed to 268.Ar utility 269(including 270.Dv NULL 271terminators) and the current environment will be less than or equal to 272this number. 273The current default value for 274.Ar size 275is 276.Dv ARG_MAX 277- 4096. 278.It Fl t 279Echo the command to be executed to standard error immediately before it 280is executed. 281.It Fl x 282Force 283.Nm 284to terminate immediately if a command line containing 285.Ar number 286arguments will not fit in the specified (or default) command line length. 287.El 288.Pp 289If 290.Ar utility 291is omitted, 292.Xr echo 1 293is used. 294.Pp 295Undefined behavior may occur if 296.Ar utility 297reads from the standard input. 298.Pp 299The 300.Nm 301utility exits immediately (without processing any further input) if a 302command line cannot be assembled, 303.Ar utility 304cannot be invoked, an invocation of 305.Ar utility 306is terminated by a signal, 307or an invocation of 308.Ar utility 309exits with a value of 255. 310.Sh FILES 311.Bl -tag -width /dev/tty -compact 312.It Pa /dev/tty 313used to read responses in prompt mode 314.El 315.Sh EXIT STATUS 316.Nm 317exits with one of the following values: 318.Bl -tag -width Ds -compact 319.It 0 320All invocations of 321.Ar utility 322returned a zero exit status. 323.It 123 324One or more invocations of 325.Ar utility 326returned a nonzero exit status. 327.It 124 328The 329.Ar utility 330exited with a 255 exit status. 331.It 125 332The 333.Ar utility 334was killed or stopped by a signal. 335.It 126 336The 337.Ar utility 338was found but could not be invoked. 339.It 127 340The 341.Ar utility 342could not be found. 343.It 1 344Some other error occurred. 345.El 346.Sh SEE ALSO 347.Xr echo 1 , 348.Xr find 1 , 349.Xr execvp 3 350.Sh STANDARDS 351The 352.Nm 353utility is expected to be 354.St -p1003.2 355compliant. 356The 357.Fl J , o , P , R , 358and 359.Fl S 360options are non-standard 361.Fx 362extensions which may not be available on other operating systems. 363.Sh HISTORY 364The 365.Nm 366utility appeared in PWB UNIX 1.0. 367It made its first BSD appearance in the 4.3 Reno release. 368.Pp 369The meaning of 123, 124, and 125 exit values and the 370.Fl 0 371option were taken from GNU xargs. 372.Sh BUGS 373If 374.Ar utility 375attempts to invoke another command such that the number of arguments or the 376size of the environment is increased, it risks 377.Xr execvp 3 378failing with 379.Er E2BIG . 380.Pp 381The 382.Nm 383utility does not take multibyte characters into account when performing 384string comparisons for the 385.Fl I 386and 387.Fl J 388options, which may lead to incorrect results in some locales. 389