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 March 1, 2017 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 213Compatibility with GNU 214.Nm . 215The GNU version of 216.Nm 217runs the 218.Ar utility 219argument at least once, even if 220.Nm 221input is empty, and it supports a 222.Fl r 223option to inhibit this behavior. 224The 225.Dx 226version of 227.Nm 228does not run the 229.Ar utility 230argument on empty input, but it supports the 231.Fl r 232option for command-line compatibility with GNU 233.Nm , 234but the 235.Fl r 236option does nothing in the 237.Dx 238version of 239.Nm . 240.It Fl R Ar replacements 241Specify the maximum number of arguments that 242.Fl I 243will do replacement in. 244.It Fl s Ar size 245Set the maximum number of bytes for the command line length provided to 246.Ar utility . 247The sum of the length of the utility name, the arguments passed to 248.Ar utility 249(including 250.Dv NULL 251terminators) and the current environment will be less than or equal to 252this number. 253The current default value for 254.Ar size 255is 256.Dv ARG_MAX 257- 4096. 258.It Fl t 259Echo the command to be executed to standard error immediately before it 260is executed. 261.It Fl x 262Force 263.Nm 264to terminate immediately if a command line containing 265.Ar number 266arguments will not fit in the specified (or default) command line length. 267.El 268.Pp 269If 270.Ar utility 271is omitted, 272.Xr echo 1 273is used. 274.Pp 275Undefined behavior may occur if 276.Ar utility 277reads from the standard input. 278.Pp 279The 280.Nm 281utility exits immediately (without processing any further input) if a 282command line cannot be assembled, 283.Ar utility 284cannot be invoked, an invocation of 285.Ar utility 286is terminated by a signal, 287or an invocation of 288.Ar utility 289exits with a value of 255. 290.Sh EXIT STATUS 291The 292.Nm 293utility exits with a value of 0 if no error occurs. 294If 295.Ar utility 296cannot be found, 297.Nm 298exits with a value of 127, otherwise if 299.Ar utility 300cannot be executed, 301.Nm 302exits with a value of 126. 303If any other error occurs, 304.Nm 305exits with a value of 1. 306.Sh SEE ALSO 307.Xr echo 1 , 308.Xr find 1 , 309.Xr execvp 3 310.Sh STANDARDS 311The 312.Nm 313utility is expected to be 314.St -p1003.2 315compliant. 316The 317.Fl J , o , P 318and 319.Fl R 320options are non-standard 321.Dx 322extensions which may not be available on other operating systems. 323.Sh HISTORY 324The 325.Nm 326command appeared in PWB 327.Ux . 328.Sh BUGS 329If 330.Ar utility 331attempts to invoke another command such that the number of arguments or the 332size of the environment is increased, it risks 333.Xr execvp 3 334failing with 335.Er E2BIG . 336