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