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 August 2, 2004 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 0opt 49.Op Fl E Ar eofstr 50.Oo 51.Fl I Ar replstr 52.Op Fl R Ar replacements 53.Oc 54.Op Fl J Ar replstr 55.Op Fl L Ar number 56.Oo 57.Fl n Ar number 58.Op Fl x 59.Oc 60.Op Fl P Ar maxprocs 61.Op Fl s Ar size 62.Op Ar utility Op Ar argument ... 63.Sh DESCRIPTION 64The 65.Nm 66utility reads space, tab, newline and end-of-file delimited strings 67from the standard input and executes 68.Ar utility 69with the strings as 70arguments. 71.Pp 72Any arguments specified on the command line are given to 73.Ar utility 74upon each invocation, followed by some number of the arguments read 75from the standard input of 76.Nm . 77This is repeated until standard input is exhausted. 78.Pp 79Spaces, tabs and newlines may be embedded in arguments using single 80(``\ '\ '') 81or double (``"'') quotes or backslashes (``\e''). 82Single quotes escape all non-single quote characters, excluding newlines, 83up to the matching single quote. 84Double quotes escape all non-double quote characters, excluding newlines, 85up to the matching double quote. 86Any single character, including newlines, may be escaped by a backslash. 87.Pp 88The options are as follows: 89.Bl -tag -width indent 90.It Fl 0 91Change 92.Nm 93to expect NUL 94(``\\0'') 95characters as separators, instead of spaces and newlines. 96This is expected to be used in concert with the 97.Fl print0 98function in 99.Xr find 1 . 100.It Fl E Ar eofstr 101Use 102.Ar eofstr 103as a logical EOF marker. 104.It Fl I Ar replstr 105Execute 106.Ar utility 107for each input line, replacing one or more occurrences of 108.Ar replstr 109in up to 110.Ar replacements 111(or 5 if no 112.Fl R 113flag is specified) arguments to 114.Ar utility 115with the entire line of input. 116The resulting arguments, after replacement is done, will not be allowed to grow 117beyond 255 bytes; this is implemented by concatenating as much of the argument 118containing 119.Ar replstr 120as possible, to the constructed arguments to 121.Ar utility , 122up to 255 bytes. 123The 255 byte limit does not apply to arguments to 124.Ar utility 125which do not contain 126.Ar replstr , 127and furthermore, no replacement will be done on 128.Ar utility 129itself. 130Implies 131.Fl x . 132.It Fl J Ar replstr 133If this option is specified, 134.Nm 135will use the data read from standard input to replace the first occurrence of 136.Ar replstr 137instead of appending that data after all other arguments. 138This option will not affect how many arguments will be read from input 139.Pq Fl n , 140or the size of the command(s) 141.Nm 142will generate 143.Pq Fl s . 144The option just moves where those arguments will be placed in the command(s) 145that are executed. 146The 147.Ar replstr 148must show up as a distinct 149.Ar argument 150to 151.Nm . 152It will not be recognized if, for instance, it is in the middle of a 153quoted string. 154Furthermore, only the first occurrence of the 155.Ar replstr 156will be replaced. 157For example, the following command will copy the list of files and 158directories which start with an uppercase letter in the current 159directory to 160.Pa destdir : 161.Pp 162.Dl /bin/ls -1d [A-Z]* | xargs -J % cp -rp % destdir 163.Pp 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 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 202Parallel mode: run at most 203.Ar maxprocs 204invocations of 205.Ar utility 206at once. 207.It Fl p 208Echo each command to be executed and ask the user whether it should be 209executed. 210An affirmative response, 211.Ql y 212in the POSIX locale, 213causes the command to be executed, any other response causes it to be 214skipped. 215No commands are executed if the process is not attached to a terminal. 216.It Fl R Ar replacements 217Specify the maximum number of arguments that 218.Fl I 219will do replacement in. 220If 221.Ar replacements 222is negative, the number of arguments in which to replace is unbounded. 223.It Fl s Ar size 224Set the maximum number of bytes for the command line length provided to 225.Ar utility . 226The sum of the length of the utility name, the arguments passed to 227.Ar utility 228(including 229.Dv NULL 230terminators) and the current environment will be less than or equal to 231this number. 232The current default value for 233.Ar size 234is 235.Dv ARG_MAX 236- 4096. 237.It Fl t 238Echo the command to be executed to standard error immediately before it 239is executed. 240.It Fl x 241Force 242.Nm 243to terminate immediately if a command line containing 244.Ar number 245arguments will not fit in the specified (or default) command line length. 246.El 247.Pp 248If 249.Ar utility 250is omitted, 251.Xr echo 1 252is used. 253.Pp 254Undefined behavior may occur if 255.Ar utility 256reads from the standard input. 257.Pp 258The 259.Nm 260utility exits immediately (without processing any further input) if a 261command line cannot be assembled, 262.Ar utility 263cannot be invoked, an invocation of 264.Ar utility 265is terminated by a signal, 266or an invocation of 267.Ar utility 268exits with a value of 255. 269.Sh EXIT STATUS 270The 271.Nm 272utility exits with a value of 0 if no error occurs. 273If 274.Ar utility 275cannot be found, 276.Nm 277exits with a value of 127, otherwise if 278.Ar utility 279cannot be executed, 280.Nm 281exits with a value of 126. 282If any other error occurs, 283.Nm 284exits with a value of 1. 285.Sh SEE ALSO 286.Xr echo 1 , 287.Xr find 1 , 288.Xr execvp 3 289.Sh STANDARDS 290The 291.Nm 292utility is expected to be 293.St -p1003.2 294compliant. 295The 296.Fl J , o , P 297and 298.Fl R 299options are non-standard 300.Fx 301extensions which may not be available on other operating systems. 302.Sh HISTORY 303The 304.Nm 305utility appeared in PWB UNIX. 306.Sh BUGS 307If 308.Ar utility 309attempts to invoke another command such that the number of arguments or the 310size of the environment is increased, it risks 311.Xr execvp 3 312failing with 313.Er E2BIG . 314.Pp 315The 316.Nm 317utility does not take multibyte characters into account when performing 318string comparisons for the 319.Fl I 320and 321.Fl J 322options, which may lead to incorrect results in some locales. 323