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