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. 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 September 21, 2020 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 , Fl -null 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 , Fl -max-args= Ns 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 , Fl -max-procs= Ns Ar maxprocs 205Parallel mode: run at most 206.Ar maxprocs 207invocations of 208.Ar utility 209at once. 210If 211.Ar maxprocs 212is set to 0, 213.Nm 214will run as many processes as possible. 215.It Fl p , Fl -interactive 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 , Fl -no-run-if-empty 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 , Fl -max-chars= Ns 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 , Fl -verbose 281Echo the command to be executed to standard error immediately before it 282is executed. 283.It Fl x , Fl -exit 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 301If a command line cannot be assembled, or 302cannot be invoked, or if an invocation of 303.Ar utility 304is terminated by a signal, 305or an invocation of 306.Ar utility 307exits with a value of 255, the 308.Nm 309utility stops processing input and exits after all invocations of 310.Ar utility 311finish processing. 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 EXAMPLES 329Create a 3x3 matrix with numbers from 1 to 9. 330Every 331.Xr echo 1 332instance receives three lines as arguments: 333.Bd -literal -offset indent 334$ seq 1 9 | xargs -L3 echo 3351 2 3 3364 5 6 3377 8 9 338.Ed 339.Pp 340Duplicate every line from standard input: 341.Bd -literal -offset indent 342$ echo -e "one\\ntwo\\nthree" | xargs -I % echo % % 343one one 344two two 345three three 346.Ed 347.Pp 348Execute at most 2 concurrent instances of 349.Xr find 1 350every one of them using one of the directories from the standard input: 351.Bd -literal -offset indent 352echo -e "/usr/ports\\n/etc\\n/usr/local" | xargs -J % -P2 -n1 find % -name file 353.Ed 354.Sh SEE ALSO 355.Xr echo 1 , 356.Xr find 1 , 357.Xr execvp 3 358.Sh STANDARDS 359The 360.Nm 361utility is expected to be 362.St -p1003.2 363compliant. 364The 365.Fl J , o , P , R 366and 367.Fl S 368options are non-standard 369.Fx 370extensions which may not be available on other operating systems. 371.Sh HISTORY 372The 373.Nm 374utility appeared in PWB UNIX. 375.Sh BUGS 376If 377.Ar utility 378attempts to invoke another command such that the number of arguments or the 379size of the environment is increased, it risks 380.Xr execvp 3 381failing with 382.Er E2BIG . 383.Pp 384The 385.Nm 386utility does not take multibyte characters into account when performing 387string comparisons for the 388.Fl I 389and 390.Fl J 391options, which may lead to incorrect results in some locales. 392