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$ 34.\" $xMach: xargs.1,v 1.2 2002/02/23 05:23:37 tim Exp $ 35.\" 36.Dd March 16, 2012 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 0oprt 45.Op Fl E Ar eofstr 46.Oo 47.Fl I Ar replstr 48.Op Fl R Ar replacements 49.Op Fl S Ar replsize 50.Oc 51.Op Fl J Ar replstr 52.Op Fl L Ar number 53.Oo 54.Fl n Ar number 55.Op Fl x 56.Oc 57.Op Fl P Ar maxprocs 58.Op Fl s Ar size 59.Op Ar utility Op Ar argument ... 60.Sh DESCRIPTION 61The 62.Nm 63utility reads space, tab, newline and end-of-file delimited strings 64from the standard input and executes 65.Ar utility 66with the strings as 67arguments. 68.Pp 69Any arguments specified on the command line are given to 70.Ar utility 71upon each invocation, followed by some number of the arguments read 72from the standard input of 73.Nm . 74This is repeated 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 115.Ar replsize 116(or 255 if no 117.Fl S 118flag is specified) 119bytes; 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 125.Ar replsize 126bytes. 127The size limit does not apply to arguments to 128.Ar utility 129which do not contain 130.Ar replstr , 131and furthermore, no replacement will be done on 132.Ar utility 133itself. 134Implies 135.Fl x . 136.It Fl J Ar replstr 137If this option is specified, 138.Nm 139will use the data read from standard input to replace the first occurrence of 140.Ar replstr 141instead of appending that data after all other arguments. 142This option will not affect how many arguments will be read from input 143.Pq Fl n , 144or the size of the command(s) 145.Nm 146will generate 147.Pq Fl s . 148The option just moves where those arguments will be placed in the command(s) 149that are executed. 150The 151.Ar replstr 152must show up as a distinct 153.Ar argument 154to 155.Nm . 156It will not be recognized if, for instance, it is in the middle of a 157quoted string. 158Furthermore, only the first occurrence of the 159.Ar replstr 160will be replaced. 161For example, the following command will copy the list of files and 162directories which start with an uppercase letter in the current 163directory to 164.Pa destdir : 165.Pp 166.Dl /bin/ls -1d [A-Z]* | xargs -J % cp -Rp % destdir 167.Pp 168.It Fl L Ar number 169Call 170.Ar utility 171for every 172.Ar number 173lines read. 174If EOF is reached and fewer lines have been read than 175.Ar number 176then 177.Ar utility 178will be called with the available lines. 179.It Fl n Ar number 180Set the maximum number of arguments taken from standard input for each 181invocation of 182.Ar utility . 183An invocation of 184.Ar utility 185will use less than 186.Ar number 187standard input arguments if the number of bytes accumulated (see the 188.Fl s 189option) exceeds the specified 190.Ar size 191or there are fewer than 192.Ar number 193arguments remaining for the last invocation of 194.Ar utility . 195The current default value for 196.Ar number 197is 5000. 198.It Fl o 199Reopen stdin as 200.Pa /dev/tty 201in the child process before executing the command. 202This is useful if you want 203.Nm 204to run an interactive application. 205.It Fl P Ar maxprocs 206Parallel mode: run at most 207.Ar maxprocs 208invocations of 209.Ar utility 210at once. 211.It Fl p 212Echo each command to be executed and ask the user whether it should be 213executed. 214An affirmative response, 215.Ql y 216in the POSIX locale, 217causes the command to be executed, any other response causes it to be 218skipped. 219No commands are executed if the process is not attached to a terminal. 220.It Fl r 221Compatibility with GNU 222.Nm . 223The GNU version of 224.Nm 225runs the 226.Ar utility 227argument at least once, even if 228.Nm 229input is empty, and it supports a 230.Fl r 231option to inhibit this behavior. 232The 233.Fx 234version of 235.Nm 236does not run the 237.Ar utility 238argument on empty input, but it supports the 239.Fl r 240option for command-line compatibility with GNU 241.Nm , 242but the 243.Fl r 244option does nothing in the 245.Fx 246version of 247.Nm . 248.It Fl R Ar replacements 249Specify the maximum number of arguments that 250.Fl I 251will do replacement in. 252If 253.Ar replacements 254is negative, the number of arguments in which to replace is unbounded. 255.It Fl S Ar replsize 256Specify the amount of space (in bytes) that 257.Fl I 258can use for replacements. 259The default for 260.Ar replsize 261is 255. 262.It Fl s Ar size 263Set the maximum number of bytes for the command line length provided to 264.Ar utility . 265The sum of the length of the utility name, the arguments passed to 266.Ar utility 267(including 268.Dv NULL 269terminators) and the current environment will be less than or equal to 270this number. 271The current default value for 272.Ar size 273is 274.Dv ARG_MAX 275- 4096. 276.It Fl t 277Echo the command to be executed to standard error immediately before it 278is executed. 279.It Fl x 280Force 281.Nm 282to terminate immediately if a command line containing 283.Ar number 284arguments will not fit in the specified (or default) command line length. 285.El 286.Pp 287If 288.Ar utility 289is omitted, 290.Xr echo 1 291is used. 292.Pp 293Undefined behavior may occur if 294.Ar utility 295reads from the standard input. 296.Pp 297If a command line cannot be assembled, or 298cannot be invoked, or if an invocation of 299.Ar utility 300is terminated by a signal, 301or an invocation of 302.Ar utility 303exits with a value of 255, the 304.Nm 305utility stops processing input and exits after all invocations of 306.Ar utility 307finish processing. 308.Sh EXIT STATUS 309The 310.Nm 311utility exits with a value of 0 if no error occurs. 312If 313.Ar utility 314cannot be found, 315.Nm 316exits with a value of 127, otherwise if 317.Ar utility 318cannot be executed, 319.Nm 320exits with a value of 126. 321If any other error occurs, 322.Nm 323exits with a value of 1. 324.Sh SEE ALSO 325.Xr echo 1 , 326.Xr find 1 , 327.Xr execvp 3 328.Sh STANDARDS 329The 330.Nm 331utility is expected to be 332.St -p1003.2 333compliant. 334The 335.Fl J , o , P, R 336and 337.Fl S 338options are non-standard 339.Fx 340extensions which may not be available on other operating systems. 341.Sh HISTORY 342The 343.Nm 344utility appeared in PWB UNIX. 345.Sh BUGS 346If 347.Ar utility 348attempts to invoke another command such that the number of arguments or the 349size of the environment is increased, it risks 350.Xr execvp 3 351failing with 352.Er E2BIG . 353.Pp 354The 355.Nm 356utility does not take multibyte characters into account when performing 357string comparisons for the 358.Fl I 359and 360.Fl J 361options, which may lead to incorrect results in some locales. 362