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