1.\" $OpenBSD: xargs.1,v 1.29 2020/07/19 13:19:25 schwarze Exp $ 2.\" $FreeBSD: xargs.1,v 1.30 2003/05/21 21:07:28 ru Exp $$ 3.\" 4.\" Copyright (c) 1990, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" John B. Roll Jr. and the Institute of Electrical and Electronics 9.\" Engineers, Inc. 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in the 18.\" documentation and/or other materials provided with the distribution. 19.\" 3. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)xargs.1 8.1 (Berkeley) 6/6/93 36.\" 37.Dd $Mdocdate: July 19 2020 $ 38.Dt XARGS 1 39.Os 40.Sh NAME 41.Nm xargs 42.Nd construct argument list(s) and execute utility 43.Sh SYNOPSIS 44.Nm xargs 45.Bk -words 46.Op Fl 0oprt 47.Op Fl E Ar eofstr 48.Oo 49.Fl I Ar replstr 50.Op Fl R Ar replacements 51.Oc 52.Op Fl J Ar replstr 53.Op Fl L Ar number 54.Oo 55.Fl n Ar number 56.Op Fl x 57.Oc 58.Op Fl P Ar maxprocs 59.Op Fl s Ar size 60.Op Ar utility Op Ar argument ... 61.Ek 62.Sh DESCRIPTION 63The 64.Nm 65utility reads space, tab, newline, and end-of-file delimited strings 66from the standard input and executes the specified 67.Ar utility 68with the strings as 69arguments. 70.Pp 71Any arguments specified on the command line are given to the 72.Ar utility 73upon each invocation, followed by some number of the arguments read 74from standard input. 75The 76.Ar utility 77is repeatedly executed one or more times until standard input 78is exhausted. 79.Pp 80Spaces, tabs and newlines may be embedded in arguments using single 81.Pq Ql ' 82or double 83.Pq Ql \&" 84quotes or backslashes 85.Pq Ql \e . 86Single quotes escape all non-single quote characters, excluding newlines, 87up to the matching single quote. 88Double quotes escape all non-double quote characters, excluding newlines, 89up to the matching double quote. 90Any single character, including newlines, may be escaped by a backslash. 91.Pp 92The options are as follows: 93.Bl -tag -width Ds 94.It Fl 0 95Change 96.Nm 97to expect NUL 98.Pq Ql \e0 99characters as separators, instead of spaces and newlines. 100The quoting mechanisms described above are not performed. 101This option is expected to be used in concert with the 102.Fl print0 103function in 104.Xr find 1 . 105.It Fl E Ar eofstr 106Use 107.Ar eofstr 108as a logical EOF marker. 109.It Fl I Ar replstr 110Execute 111.Ar utility 112for each input line, replacing one or more occurrences of 113.Ar replstr 114in up to 115.Ar replacements 116(or 5 if no 117.Fl R 118flag is specified) arguments to 119.Ar utility 120with the entire line of input. 121The resulting arguments, after replacement is done, will not be allowed to grow 122beyond 255 bytes; this is implemented by concatenating as much of the argument 123containing 124.Ar replstr 125as possible, to the constructed arguments to 126.Ar utility , 127up to 255 bytes. 128The 255 byte limit does not apply to arguments to 129.Ar utility 130which do not contain 131.Ar replstr , 132and furthermore, no replacement will be done on 133.Ar utility 134itself. 135Implies 136.Fl x . 137.It Fl J Ar replstr 138If this option is specified, 139.Nm 140will use the data read from standard input to replace the first occurrence of 141.Ar replstr 142instead of appending that data after all other arguments. 143This option will not effect how many arguments will be read from input 144.Pq Fl n , 145or the size of the command(s) 146.Nm 147will generate 148.Pq Fl s . 149The option just moves where those arguments will be placed in the command(s) 150that are executed. 151The 152.Ar replstr 153must show up as a distinct 154.Ar argument 155to 156.Nm xargs . 157It will not be recognized if, for instance, it is in the middle of a 158quoted string. 159Furthermore, only the first occurrence of the 160.Ar replstr 161will be replaced. 162For example, the following command will copy the list of files and 163directories which start with an uppercase letter in the current 164directory to 165.Pa destdir : 166.Pp 167.Dl "/bin/ls -1d [A-Z]* | xargs -J % cp -Rp % destdir" 168.It Fl L Ar number 169Call 170.Ar utility 171for every 172.Ar number 173of non-empty lines read. 174A line ending in unescaped white space and the next non-empty line 175are considered to form one single line. 176If EOF is reached and fewer than 177.Ar number 178lines have been read then 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. 216If the answer starts with 217.Ql y 218or 219.Ql Y , 220the command is executed; otherwise it is skipped. 221No commands are executed if the process is not attached to a terminal. 222.It Fl R Ar replacements 223Specify the maximum number of arguments that 224.Fl I 225will do replacement in. 226If 227.Ar replacements 228is negative, the number of arguments in which to replace is unbounded. 229.It Fl r 230Do not run the command if there are no arguments. 231Normally the command is executed at least once 232even if there are no arguments. 233.It Fl s Ar size 234Set the maximum number of bytes for the command line length provided to 235.Ar utility . 236The sum of the length of the utility name, the arguments passed to 237.Ar utility 238(including 239.Dv NUL 240terminators) and the current environment will be less than or equal to 241this number. 242The current default value for 243.Ar size 244is 245.Dv ARG_MAX 246- 4096. 247.It Fl t 248Echo the command to be executed to standard error immediately before it 249is executed. 250.It Fl x 251Force 252.Nm 253to terminate immediately if a command line containing 254.Ar number 255arguments will not fit in the specified (or default) command line length. 256.El 257.Pp 258If no 259.Ar utility 260is specified, 261.Xr echo 1 262is used. 263.Pp 264Undefined behavior may occur if 265.Ar utility 266reads from the standard input. 267.Pp 268The 269.Nm 270utility exits immediately (without processing any further input) if a 271command line cannot be assembled, 272.Ar utility 273cannot be invoked, an invocation of 274.Ar utility 275is terminated by a signal, 276or an invocation of 277.Ar utility 278exits with a value of 255. 279.Sh EXIT STATUS 280.Nm 281exits with one of the following values: 282.Pp 283.Bl -tag -width Ds -offset indent -compact 284.It 0 285All invocations of 286.Ar utility 287returned a zero exit status. 288.It 123 289One or more invocations of 290.Ar utility 291returned a nonzero exit status. 292.It 124 293The 294.Ar utility 295exited with a 255 exit status. 296.It 125 297The 298.Ar utility 299was killed or stopped by a signal. 300.It 126 301The 302.Ar utility 303was found but could not be executed. 304.It 127 305The 306.Ar utility 307could not be found. 308.It 1 309Some other error occurred. 310.El 311.Sh SEE ALSO 312.Xr echo 1 , 313.Xr find 1 , 314.Xr execvp 3 315.Sh STANDARDS 316The 317.Nm 318utility is compliant with the 319.St -p1003.1-2008 320specification. 321.Pp 322The flags 323.Op Fl IL 324are marked by 325.St -p1003.1-2008 326as being an X/Open System Interfaces option. 327.Pp 328The flags 329.Op Fl 0JoPRr 330are extensions to 331.St -p1003.1-2008 . 332.Pp 333The meanings of the 123, 124, and 125 exit values were taken from GNU 334.Nm xargs . 335.Sh HISTORY 336The 337.Nm 338command appeared in PWB 339.Ux . 340.Sh BUGS 341If 342.Ar utility 343attempts to invoke another command such that the number of arguments or the 344size of the environment is increased, it risks 345.Xr execvp 3 346failing with 347.Er E2BIG . 348