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.\" $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.It Fl L Ar number 161Call 162.Ar utility 163for every 164.Ar number 165lines read. 166If EOF is reached and fewer lines have been read than 167.Ar number 168then 169.Ar utility 170will be called with the available lines. 171.It Fl n Ar number 172Set the maximum number of arguments taken from standard input for each 173invocation of 174.Ar utility . 175An invocation of 176.Ar utility 177will use less than 178.Ar number 179standard input arguments if the number of bytes accumulated (see the 180.Fl s 181option) exceeds the specified 182.Ar size 183or there are fewer than 184.Ar number 185arguments remaining for the last invocation of 186.Ar utility . 187The current default value for 188.Ar number 189is 5000. 190.It Fl o 191Reopen stdin as 192.Pa /dev/tty 193in the child process before executing the command. 194This is useful if you want 195.Nm 196to run an interactive application. 197.It Fl P Ar maxprocs 198Parallel mode: run at most 199.Ar maxprocs 200invocations of 201.Ar utility 202at once. 203.It Fl p 204Echo each command to be executed and ask the user whether it should be 205executed. 206An affirmative response, 207.Ql y 208in the POSIX locale, 209causes the command to be executed, any other response causes it to be 210skipped. 211No commands are executed if the process is not attached to a terminal. 212.It Fl R Ar replacements 213Specify the maximum number of arguments that 214.Fl I 215will do replacement in. 216.It Fl s Ar size 217Set the maximum number of bytes for the command line length provided to 218.Ar utility . 219The sum of the length of the utility name, the arguments passed to 220.Ar utility 221(including 222.Dv NULL 223terminators) and the current environment will be less than or equal to 224this number. 225The current default value for 226.Ar size 227is 228.Dv ARG_MAX 229- 4096. 230.It Fl t 231Echo the command to be executed to standard error immediately before it 232is executed. 233.It Fl x 234Force 235.Nm 236to terminate immediately if a command line containing 237.Ar number 238arguments will not fit in the specified (or default) command line length. 239.El 240.Pp 241If 242.Ar utility 243is omitted, 244.Xr echo 1 245is used. 246.Pp 247Undefined behavior may occur if 248.Ar utility 249reads from the standard input. 250.Pp 251The 252.Nm 253utility exits immediately (without processing any further input) if a 254command line cannot be assembled, 255.Ar utility 256cannot be invoked, an invocation of 257.Ar utility 258is terminated by a signal, 259or an invocation of 260.Ar utility 261exits with a value of 255. 262.Sh EXIT STATUS 263The 264.Nm 265utility exits with a value of 0 if no error occurs. 266If 267.Ar utility 268cannot be found, 269.Nm 270exits with a value of 127, otherwise if 271.Ar utility 272cannot be executed, 273.Nm 274exits with a value of 126. 275If any other error occurs, 276.Nm 277exits with a value of 1. 278.Sh SEE ALSO 279.Xr echo 1 , 280.Xr find 1 , 281.Xr execvp 3 282.Sh STANDARDS 283The 284.Nm 285utility is expected to be 286.St -p1003.2 287compliant. 288The 289.Fl J , o , P 290and 291.Fl R 292options are non-standard 293.Dx 294extensions which may not be available on other operating systems. 295.Sh HISTORY 296The 297.Nm 298command appeared in PWB 299.Ux . 300.Sh BUGS 301If 302.Ar utility 303attempts to invoke another command such that the number of arguments or the 304size of the environment is increased, it risks 305.Xr execvp 3 306failing with 307.Er E2BIG . 308