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.\" $xMach: xargs.1,v 1.2 2002/02/23 05:23:37 tim Exp $ 34.\" 35.Dd September 21, 2020 36.Dt XARGS 1 37.Os 38.Sh NAME 39.Nm xargs 40.Nd "construct argument list(s) and execute utility" 41.Sh SYNOPSIS 42.Nm 43.Op Fl 0oprt 44.Op Fl E Ar eofstr 45.Oo 46.Fl I Ar replstr 47.Op Fl R Ar replacements 48.Op Fl S Ar replsize 49.Oc 50.Op Fl J Ar replstr 51.Op Fl L Ar number 52.Oo 53.Fl n Ar number 54.Op Fl x 55.Oc 56.Op Fl P Ar maxprocs 57.Op Fl s Ar size 58.Op Ar utility Op Ar argument ... 59.Sh DESCRIPTION 60The 61.Nm 62utility reads space, tab, newline and end-of-file delimited strings 63from the standard input and executes 64.Ar utility 65with the strings as 66arguments. 67.Pp 68Any arguments specified on the command line are given to 69.Ar utility 70upon each invocation, followed by some number of the arguments read 71from the standard input of 72.Nm . 73This is repeated until standard input is exhausted. 74.Pp 75Spaces, tabs and newlines may be embedded in arguments using single 76(``\ '\ '') 77or double (``"'') quotes or backslashes (``\e''). 78Single quotes escape all non-single quote characters, excluding newlines, 79up to the matching single quote. 80Double quotes escape all non-double quote characters, excluding newlines, 81up to the matching double quote. 82Any single character, including newlines, may be escaped by a backslash. 83.Pp 84The options are as follows: 85.Bl -tag -width indent 86.It Fl 0 , Fl -null 87Change 88.Nm 89to expect NUL 90(``\\0'') 91characters as separators, instead of spaces and newlines. 92This is expected to be used in concert with the 93.Fl print0 94function in 95.Xr find 1 . 96.It Fl E Ar eofstr 97Use 98.Ar eofstr 99as a logical EOF marker. 100.It Fl I Ar replstr 101Execute 102.Ar utility 103for each input line, replacing one or more occurrences of 104.Ar replstr 105in up to 106.Ar replacements 107(or 5 if no 108.Fl R 109flag is specified) arguments to 110.Ar utility 111with the entire line of input. 112The resulting arguments, after replacement is done, will not be allowed to grow 113beyond 114.Ar replsize 115(or 255 if no 116.Fl S 117flag is specified) 118bytes; this is implemented by concatenating as much of the argument 119containing 120.Ar replstr 121as possible, to the constructed arguments to 122.Ar utility , 123up to 124.Ar replsize 125bytes. 126The size limit does not apply to arguments to 127.Ar utility 128which do not contain 129.Ar replstr , 130and furthermore, no replacement will be done on 131.Ar utility 132itself. 133Implies 134.Fl x . 135.It Fl J Ar replstr 136If this option is specified, 137.Nm 138will use the data read from standard input to replace the first occurrence of 139.Ar replstr 140instead of appending that data after all other arguments. 141This option will not affect how many arguments will be read from input 142.Pq Fl n , 143or the size of the command(s) 144.Nm 145will generate 146.Pq Fl s . 147The option just moves where those arguments will be placed in the command(s) 148that are executed. 149The 150.Ar replstr 151must show up as a distinct 152.Ar argument 153to 154.Nm . 155It will not be recognized if, for instance, it is in the middle of a 156quoted string. 157Furthermore, only the first occurrence of the 158.Ar replstr 159will be replaced. 160For example, the following command will copy the list of files and 161directories which start with an uppercase letter in the current 162directory to 163.Pa destdir : 164.Pp 165.Dl /bin/ls -1d [A-Z]* | xargs -J % cp -Rp % destdir 166.It Fl L Ar number 167Call 168.Ar utility 169for every 170.Ar number 171lines read. 172If EOF is reached and fewer lines have been read than 173.Ar number 174then 175.Ar utility 176will be called with the available lines. 177.It Fl n Ar number , Fl -max-args= Ns Ar number 178Set the maximum number of arguments taken from standard input for each 179invocation of 180.Ar utility . 181An invocation of 182.Ar utility 183will use less than 184.Ar number 185standard input arguments if the number of bytes accumulated (see the 186.Fl s 187option) exceeds the specified 188.Ar size 189or there are fewer than 190.Ar number 191arguments remaining for the last invocation of 192.Ar utility . 193The current default value for 194.Ar number 195is 5000. 196.It Fl o 197Reopen stdin as 198.Pa /dev/tty 199in the child process before executing the command. 200This is useful if you want 201.Nm 202to run an interactive application. 203.It Fl P Ar maxprocs , Fl -max-procs= Ns Ar maxprocs 204Parallel mode: run at most 205.Ar maxprocs 206invocations of 207.Ar utility 208at once. 209If 210.Ar maxprocs 211is set to 0, 212.Nm 213will run as many processes as possible. 214.It Fl p , Fl -interactive 215Echo each command to be executed and ask the user whether it should be 216executed. 217An affirmative response, 218.Ql y 219in the POSIX locale, 220causes the command to be executed, any other response causes it to be 221skipped. 222No commands are executed if the process is not attached to a terminal. 223.It Fl r , Fl -no-run-if-empty 224Compatibility with GNU 225.Nm . 226The GNU version of 227.Nm 228runs the 229.Ar utility 230argument at least once, even if 231.Nm 232input is empty, and it supports a 233.Fl r 234option to inhibit this behavior. 235The 236.Fx 237version of 238.Nm 239does not run the 240.Ar utility 241argument on empty input, but it supports the 242.Fl r 243option for command-line compatibility with GNU 244.Nm , 245but the 246.Fl r 247option does nothing in the 248.Fx 249version of 250.Nm . 251.It Fl R Ar replacements 252Specify the maximum number of arguments that 253.Fl I 254will do replacement in. 255If 256.Ar replacements 257is negative, the number of arguments in which to replace is unbounded. 258.It Fl S Ar replsize 259Specify the amount of space (in bytes) that 260.Fl I 261can use for replacements. 262The default for 263.Ar replsize 264is 255. 265.It Fl s Ar size , Fl -max-chars= Ns Ar size 266Set the maximum number of bytes for the command line length provided to 267.Ar utility . 268The sum of the length of the utility name, the arguments passed to 269.Ar utility 270(including 271.Dv NULL 272terminators) and the current environment will be less than or equal to 273this number. 274The current default value for 275.Ar size 276is 277.Dv ARG_MAX 278- 4096. 279.It Fl t , Fl -verbose 280Echo the command to be executed to standard error immediately before it 281is executed. 282.It Fl x , Fl -exit 283Force 284.Nm 285to terminate immediately if a command line containing 286.Ar number 287arguments will not fit in the specified (or default) command line length. 288.El 289.Pp 290If 291.Ar utility 292is omitted, 293.Xr echo 1 294is used. 295.Pp 296Undefined behavior may occur if 297.Ar utility 298reads from the standard input. 299.Pp 300If a command line cannot be assembled, or 301cannot be invoked, or if an invocation of 302.Ar utility 303is terminated by a signal, 304or an invocation of 305.Ar utility 306exits with a value of 255, the 307.Nm 308utility stops processing input and exits after all invocations of 309.Ar utility 310finish processing. 311.Sh EXIT STATUS 312The 313.Nm 314utility exits with a value of 0 if no error occurs. 315If 316.Ar utility 317cannot be found, 318.Nm 319exits with a value of 127, otherwise if 320.Ar utility 321cannot be executed, 322.Nm 323exits with a value of 126. 324If any other error occurs, 325.Nm 326exits with a value of 1. 327.Sh EXAMPLES 328Create a 3x3 matrix with numbers from 1 to 9. 329Every 330.Xr echo 1 331instance receives three lines as arguments: 332.Bd -literal -offset indent 333$ seq 1 9 | xargs -L3 echo 3341 2 3 3354 5 6 3367 8 9 337.Ed 338.Pp 339Duplicate every line from standard input: 340.Bd -literal -offset indent 341$ echo -e "one\\ntwo\\nthree" | xargs -I % echo % % 342one one 343two two 344three three 345.Ed 346.Pp 347Execute at most 2 concurrent instances of 348.Xr find 1 349every one of them using one of the directories from the standard input: 350.Bd -literal -offset indent 351echo -e "/usr/ports\\n/etc\\n/usr/local" | xargs -J % -P2 -n1 find % -name file 352.Ed 353.Sh SEE ALSO 354.Xr echo 1 , 355.Xr find 1 , 356.Xr execvp 3 357.Sh STANDARDS 358The 359.Nm 360utility is expected to be 361.St -p1003.2 362compliant. 363The 364.Fl J , o , P , R 365and 366.Fl S 367options are non-standard 368.Fx 369extensions which may not be available on other operating systems. 370.Sh HISTORY 371The 372.Nm 373utility appeared in PWB UNIX. 374.Sh BUGS 375If 376.Ar utility 377attempts to invoke another command such that the number of arguments or the 378size of the environment is increased, it risks 379.Xr execvp 3 380failing with 381.Er E2BIG . 382.Pp 383The 384.Nm 385utility does not take multibyte characters into account when performing 386string comparisons for the 387.Fl I 388and 389.Fl J 390options, which may lead to incorrect results in some locales. 391