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