1.\" $OpenBSD: xargs.1,v 1.15 2005/09/12 09:44:59 jmc Exp $ 2.\" $FreeBSD: xargs.1,v 1.30 2003/05/21 21:07:28 ru Exp $$ 3.\" 4.\" Copyright (c) 1990, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" John B. Roll Jr. and the Institute of Electrical and Electronics 9.\" Engineers, Inc. 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in the 18.\" documentation and/or other materials provided with the distribution. 19.\" 3. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)xargs.1 8.1 (Berkeley) 6/6/93 36.\" 37.Dd May 7, 2001 38.Dt XARGS 1 39.Os 40.Sh NAME 41.Nm xargs 42.Nd "construct argument list(s) and execute utility" 43.Sh SYNOPSIS 44.Nm xargs 45.Bk -words 46.Op Fl 0oprt 47.Op Fl E Ar eofstr 48.Oo 49.Fl I Ar replstr 50.Op Fl R Ar replacements 51.Oc 52.Op Fl J Ar replstr 53.Op Fl L Ar number 54.Oo 55.Fl n Ar number 56.Op Fl x 57.Oc 58.Op Fl P Ar maxprocs 59.Op Fl s Ar size 60.Op Ar utility Op Ar argument ... 61.Ek 62.Sh DESCRIPTION 63The 64.Nm 65utility reads space, tab, newline, and end-of-file delimited strings 66from the standard input and executes the specified 67.Ar utility 68with the strings as 69arguments. 70.Pp 71Any arguments specified on the command line are given to the 72.Ar utility 73upon each invocation, followed by some number of the arguments read 74from standard input. 75The 76.Ar utility 77is repeatedly executed one or more times until standard input 78is exhausted. 79.Pp 80Spaces, tabs and newlines may be embedded in arguments using single 81.Pq Ql ' 82or double 83.Pq Ql \&" 84quotes or backslashes 85.Pq Ql \e . 86Single quotes escape all non-single quote characters, excluding newlines, 87up to the matching single quote. 88Double quotes escape all non-double quote characters, excluding newlines, 89up to the matching double quote. 90Any single character, including newlines, may be escaped by a backslash. 91.Pp 92The options are as follows: 93.Bl -tag -width Ds 94.It Fl 0 95Change 96.Nm 97to expect NUL 98.Pq Ql \e0 99characters as separators, instead of spaces and newlines. 100This is expected to be used in concert with the 101.Fl print0 102function in 103.Xr find 1 . 104.It Fl E Ar eofstr 105Use 106.Ar eofstr 107as a logical EOF marker. 108.It Fl I Ar replstr 109Execute 110.Ar utility 111for each input line, replacing one or more occurrences of 112.Ar replstr 113in up to 114.Ar replacements 115(or 5 if no 116.Fl R 117flag is specified) arguments to 118.Ar utility 119with the entire line of input. 120The resulting arguments, after replacement is done, will not be allowed to grow 121beyond 255 bytes; this is implemented by concatenating as much of the argument 122containing 123.Ar replstr 124as possible, to the constructed arguments to 125.Ar utility , 126up to 255 bytes. 127The 255 byte 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 effect 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 xargs . 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.It Fl L Ar number 168Call 169.Ar utility 170for every 171.Ar number 172of lines read. 173If EOF is reached and fewer than 174.Ar number 175lines have been read then 176.Ar utility 177will be called with the available lines. 178.It Fl n Ar number 179Set the maximum number of arguments taken from standard input for each 180invocation of 181.Ar utility . 182An invocation of 183.Ar utility 184will use less than 185.Ar number 186standard input arguments if the number of bytes accumulated (see the 187.Fl s 188option) exceeds the specified 189.Ar size 190or there are fewer than 191.Ar number 192arguments remaining for the last invocation of 193.Ar utility . 194The current default value for 195.Ar number 196is 5000. 197.It Fl o 198Reopen stdin as 199.Pa /dev/tty 200in the child process before executing the command. 201This is useful if you want 202.Nm 203to run an interactive application. 204.It Fl P Ar maxprocs 205Parallel mode: run at most 206.Ar maxprocs 207invocations of 208.Ar utility 209at once. 210.It Fl p 211Echo each command to be executed and ask the user whether it should be 212executed. 213An affirmative response, 214.Ql y 215in the POSIX locale, 216causes the command to be executed, any other response causes it to be 217skipped. 218No commands are executed if the process is not attached to a terminal. 219.It Fl R Ar replacements 220Specify the maximum number of arguments that 221.Fl I 222will do replacement in. 223If 224.Ar replacements 225is negative, the number of arguments in which to replace is unbounded. 226.It Fl r 227Do not run the command if there are no arguments. 228Normally the command is executed at least once 229even if there are no arguments. 230.It Fl s Ar size 231Set the maximum number of bytes for the command line length provided to 232.Ar utility . 233The sum of the length of the utility name, the arguments passed to 234.Ar utility 235(including 236.Dv NUL 237terminators) and the current environment will be less than or equal to 238this number. 239The current default value for 240.Ar size 241is 242.Dv ARG_MAX 243- 4096. 244.It Fl t 245Echo the command to be executed to standard error immediately before it 246is executed. 247.It Fl x 248Force 249.Nm 250to terminate immediately if a command line containing 251.Ar number 252arguments will not fit in the specified (or default) command line length. 253.El 254.Pp 255If no 256.Ar utility 257is specified, 258.Xr echo 1 259is used. 260.Pp 261Undefined behavior may occur if 262.Ar utility 263reads from the standard input. 264.Pp 265The 266.Nm 267utility exits immediately (without processing any further input) if a 268command line cannot be assembled, 269.Ar utility 270cannot be invoked, an invocation of 271.Ar utility 272is terminated by a signal, 273or an invocation of 274.Ar utility 275exits with a value of 255. 276.Sh DIAGNOSTICS 277.Nm 278exits with one of the following values: 279.Pp 280.Bl -tag -width Ds -compact 281.It 0 282All invocations of 283.Ar utility 284returned a zero exit status. 285.It 123 286One or more invocations of 287.Ar utility 288returned a nonzero exit status. 289.It 124 290The 291.Ar utility 292exited with a 255 exit status. 293.It 125 294The 295.Ar utility 296was killed or stopped by a signal. 297.It 126 298The 299.Ar utility 300was found but could not be executed. 301.It 127 302The 303.Ar utility 304could not be found. 305.It 1 306Some other error occurred. 307.El 308.Sh SEE ALSO 309.Xr echo 1 , 310.Xr find 1 , 311.Xr execvp 3 312.Sh STANDARDS 313The 314.Nm 315utility is expected to be 316.St -p1003.2 317compliant. 318The 319.Fl J , o , P , R 320and 321.Fl r 322options are non-standard 323extensions which may not be available on other operating systems. 324.Pp 325The meanings of the 123, 124, and 125 exit values were taken from 326.Tn GNU 327.Nm xargs . 328.Sh HISTORY 329The 330.Nm 331command appeared in PWB UNIX. 332.Sh BUGS 333If 334.Ar utility 335attempts to invoke another command such that the number of arguments or the 336size of the environment is increased, it risks 337.Xr execvp 3 338failing with 339.Er E2BIG . 340