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.\" $xMach: xargs.1,v 1.2 2002/02/23 05:23:37 tim Exp $ 32.\" 33.Dd September 21, 2020 34.Dt XARGS 1 35.Os 36.Sh NAME 37.Nm xargs 38.Nd "construct argument list(s) and execute utility" 39.Sh SYNOPSIS 40.Nm 41.Op Fl 0oprt 42.Op Fl E Ar eofstr 43.Oo 44.Fl I Ar replstr 45.Op Fl R Ar replacements 46.Op Fl S Ar replsize 47.Oc 48.Op Fl J Ar replstr 49.Op Fl L Ar number 50.Oo 51.Fl n Ar number 52.Op Fl x 53.Oc 54.Op Fl P Ar maxprocs 55.Op Fl s Ar size 56.Op Ar utility Op Ar argument ... 57.Sh DESCRIPTION 58The 59.Nm 60utility reads space, tab, newline and end-of-file delimited strings 61from the standard input and executes 62.Ar utility 63with the strings as 64arguments. 65.Pp 66Any arguments specified on the command line are given to 67.Ar utility 68upon each invocation, followed by some number of the arguments read 69from the standard input of 70.Nm . 71This is repeated until standard input is exhausted. 72.Pp 73Spaces, tabs and newlines may be embedded in arguments using single 74(``\ '\ '') 75or double (``"'') quotes or backslashes (``\e''). 76Single quotes escape all non-single quote characters, excluding newlines, 77up to the matching single quote. 78Double quotes escape all non-double quote characters, excluding newlines, 79up to the matching double quote. 80Any single character, including newlines, may be escaped by a backslash. 81.Pp 82The options are as follows: 83.Bl -tag -width indent 84.It Fl 0 , Fl -null 85Change 86.Nm 87to expect NUL 88(``\\0'') 89characters as separators, instead of spaces and newlines. 90This is expected to be used in concert with the 91.Fl print0 92function in 93.Xr find 1 . 94.It Fl E Ar eofstr 95Use 96.Ar eofstr 97as a logical EOF marker. 98.It Fl I Ar replstr 99Execute 100.Ar utility 101for each input line, replacing one or more occurrences of 102.Ar replstr 103in up to 104.Ar replacements 105(or 5 if no 106.Fl R 107flag is specified) arguments to 108.Ar utility 109with the entire line of input. 110The resulting arguments, after replacement is done, will not be allowed to grow 111beyond 112.Ar replsize 113(or 255 if no 114.Fl S 115flag is specified) 116bytes; this is implemented by concatenating as much of the argument 117containing 118.Ar replstr 119as possible, to the constructed arguments to 120.Ar utility , 121up to 122.Ar replsize 123bytes. 124The size limit does not apply to arguments to 125.Ar utility 126which do not contain 127.Ar replstr , 128and furthermore, no replacement will be done on 129.Ar utility 130itself. 131Implies 132.Fl x . 133.It Fl J Ar replstr 134If this option is specified, 135.Nm 136will use the data read from standard input to replace the first occurrence of 137.Ar replstr 138instead of appending that data after all other arguments. 139This option will not affect how many arguments will be read from input 140.Pq Fl n , 141or the size of the command(s) 142.Nm 143will generate 144.Pq Fl s . 145The option just moves where those arguments will be placed in the command(s) 146that are executed. 147The 148.Ar replstr 149must show up as a distinct 150.Ar argument 151to 152.Nm . 153It will not be recognized if, for instance, it is in the middle of a 154quoted string. 155Furthermore, only the first occurrence of the 156.Ar replstr 157will be replaced. 158For example, the following command will copy the list of files and 159directories which start with an uppercase letter in the current 160directory to 161.Pa destdir : 162.Pp 163.Dl /bin/ls -1d [A-Z]* | xargs -J % cp -Rp % destdir 164.It Fl L Ar number 165Call 166.Ar utility 167for every 168.Ar number 169lines read. 170If EOF is reached and fewer lines have been read than 171.Ar number 172then 173.Ar utility 174will be called with the available lines. 175.It Fl n Ar number , Fl -max-args= Ns Ar number 176Set the maximum number of arguments taken from standard input for each 177invocation of 178.Ar utility . 179An invocation of 180.Ar utility 181will use less than 182.Ar number 183standard input arguments if the number of bytes accumulated (see the 184.Fl s 185option) exceeds the specified 186.Ar size 187or there are fewer than 188.Ar number 189arguments remaining for the last invocation of 190.Ar utility . 191The current default value for 192.Ar number 193is 5000. 194.It Fl o 195Reopen stdin as 196.Pa /dev/tty 197in the child process before executing the command. 198This is useful if you want 199.Nm 200to run an interactive application. 201.It Fl P Ar maxprocs , Fl -max-procs= Ns Ar maxprocs 202Parallel mode: run at most 203.Ar maxprocs 204invocations of 205.Ar utility 206at once. 207If 208.Ar maxprocs 209is set to 0, 210.Nm 211will run as many processes as possible. 212.It Fl p , Fl -interactive 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 , Fl -no-run-if-empty 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.Fx 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.Fx 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 , Fl -max-chars= Ns 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 , Fl -verbose 278Echo the command to be executed to standard error immediately before it 279is executed. 280.It Fl x , Fl -exit 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 298If a command line cannot be assembled, or 299cannot be invoked, or if an invocation of 300.Ar utility 301is terminated by a signal, 302or an invocation of 303.Ar utility 304exits with a value of 255, the 305.Nm 306utility stops processing input and exits after all invocations of 307.Ar utility 308finish processing. 309.Sh EXIT STATUS 310The 311.Nm 312utility exits with a value of 0 if no error occurs. 313If 314.Ar utility 315cannot be found, 316.Nm 317exits with a value of 127, otherwise if 318.Ar utility 319cannot be executed, 320.Nm 321exits with a value of 126. 322If any other error occurs, 323.Nm 324exits with a value of 1. 325.Sh EXAMPLES 326Create a 3x3 matrix with numbers from 1 to 9. 327Every 328.Xr echo 1 329instance receives three lines as arguments: 330.Bd -literal -offset indent 331$ seq 1 9 | xargs -L3 echo 3321 2 3 3334 5 6 3347 8 9 335.Ed 336.Pp 337Duplicate every line from standard input: 338.Bd -literal -offset indent 339$ echo -e "one\\ntwo\\nthree" | xargs -I % echo % % 340one one 341two two 342three three 343.Ed 344.Pp 345Execute at most 2 concurrent instances of 346.Xr find 1 347every one of them using one of the directories from the standard input: 348.Bd -literal -offset indent 349echo -e "/usr/ports\\n/etc\\n/usr/local" | xargs -J % -P2 -n1 find % -name file 350.Ed 351.Sh SEE ALSO 352.Xr echo 1 , 353.Xr find 1 , 354.Xr execvp 3 355.Sh STANDARDS 356The 357.Nm 358utility is expected to be 359.St -p1003.2 360compliant. 361The 362.Fl J , o , P , R 363and 364.Fl S 365options are non-standard 366.Fx 367extensions which may not be available on other operating systems. 368.Sh HISTORY 369The 370.Nm 371utility appeared in PWB UNIX. 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