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