| blob | 50a0e0f0c079a11eb712317242ff01f70e443eee |
1 .TH XARGS 1 \" -*- nroff -*-
2 .SH NAME
3 xargs \- build and execute command lines from standard input
4 .SH SYNOPSIS
5 .B xargs
6 .nh
7 [\fB\-0prtx\fR]
8 [\fB\-E \fIeof-str\fR]
9 [\fB\-e\fR[\fIeof-str\fR]]
10 [\fB\-\-eof\fR[=\fIeof-str\fR]]
11 [\fB\-\-null\fR]
12 [\fB\-d \fIdelimiter\fR]
13 [\fB\-\-delimiter \fIdelimiter\fR]
14 [\fB\-I \fIreplace-str\fR]
15 [\fB\-i\fR[\fIreplace-str\fR]]
16 [\fB\-\-replace\fR[=\fIreplace-str\fR]]
17 [\fB\-l\fR[\fImax-lines\fR]]
18 [\fB\-L \fImax-lines\fR]
19 [\fB\-\-max\-lines\fR[=\fImax-lines\fR]]
20 [\fB\-n \fImax-args\fR]
21 [\fB\-\-max\-args\fR=\fImax-args\fR]
22 [\fB\-s \fImax-chars\fR]
23 [\fB\-\-max\-chars\fR=\fImax-chars\fR]
24 [\fB\-P \fImax-procs\fR]
25 [\fB\-\-max\-procs\fR=\fImax-procs\fR]
26 [\fB\-\-interactive\fR]
27 [\fB\-\-verbose\fR]
28 [\fB\-\-exit\fR]
29 [\fB\-\-no\-run\-if\-empty\fR]
30 [\fB\-\-arg\-file\fR=\fIfile\fR]
31 [\fB\-\-show\-limits\fR]
32 [\fB\-\-version\fR]
33 [\fB\-\-help\fR]
34 [\fIcommand\fR [\fIinitial-arguments\fR]]
35 .hy
36 .SH DESCRIPTION
37 This manual page
38 documents the GNU version of
39 .BR xargs .
40 .B xargs
41 reads items from the standard input, delimited by blanks (which can be
42 protected with double or single quotes or a backslash) or newlines,
43 and executes the
44 .I command
45 (default is
46 .IR /bin/echo )
47 one or more times with any
48 .I initial-arguments
49 followed by items read from standard input. Blank lines on the
50 standard input are ignored.
51 .P
52 The command line for
53 .I command
54 is built up until it reaches a system-defined limit (unless the
55 .B \-n
56 and
57 .B \-L
58 options are used). The specified
59 .I command
60 will be invoked as many times as necessary to use up the list of input
61 items. In general, there will be many fewer invocations of
62 .I command
63 than there were items in the input. This will normally have
64 significant performance benefits. Some commands can usefully be
65 executed in parallel too; see the
66 .B \-P
67 option.
68 .P
69 Because Unix filenames can contain blanks and newlines, this default
70 behaviour is often problematic; filenames containing blanks
71 and/or newlines are incorrectly processed by
72 .BR xargs .
73 In these situations it is better to use the
74 .B \-0
75 option, which
76 prevents such problems. When using this option you will need to
77 ensure that the program which produces the input for
78 .B xargs
79 also uses a null character as a separator. If that program is
80 GNU
81 .B find
82 for example, the
83 .B \-print0
84 option does this for you.
85 .P
86 If any invocation of the command exits with a status of 255,
87 .B xargs
88 will stop immediately without reading any further input. An error
89 message is issued on stderr when this happens.
90 .SH OPTIONS
91 .TP
92 .PD 0
93 .BI "\-\-arg\-file=" file
94 .TP
95 .PD 0
96 .BI "\-a " file
97 Read items from
98 .I file
99 instead of standard input. If you use this option, stdin remains
100 unchanged when commands are run. Otherwise, stdin is redirected
101 from
102 .IR /dev/null .
104 .TP
105 .PD 0
106 .B \-\-null
107 .TP
108 .PD
109 .B \-0
110 Input items are terminated by a null character instead of by
111 whitespace, and the quotes and backslash are not special (every
112 character is taken literally). Disables the end of file string, which
113 is treated like any other argument. Useful when input items might
114 contain white space, quote marks, or backslashes. The GNU find
115 \-print0 option produces input suitable for this mode.
117 .TP
118 .PD 0
119 .BI "\-\-delimiter=" delim
120 .TP
121 .PD
122 .BI \-d " delim"
123 Input items are terminated by the specified character. Quotes and
124 backslash are not special; every character in the input is taken
125 literally. Disables the end-of-file string, which is treated like any
126 other argument. This can be used when the input consists of simply
127 newline-separated items, although it is almost always better to design
128 your program to use
129 .B \-\-null
130 where this is possible. The specified
131 delimiter may be a single character, a C-style character escape such
132 as
133 .BR \en ,
134 or an octal or hexadecimal escape code. Octal and hexadecimal
135 escape codes are understood as for the
136 .B printf
137 command. Multibyte characters are not supported.
139 .TP
140 .BI \-E " eof-str"
141 Set the end of file string to \fIeof-str\fR. If the end of file
142 string occurs as a line of input, the rest of the input is ignored.
143 If neither
144 .B \-E
145 nor
146 .B \-e
147 is used, no end of file string is used.
148 .TP
149 .PD 0
150 .BR "\-\-eof" [\fI=eof-str\fR]
151 .TP
152 .PD
153 .BR \-e [ \fIeof-str\fR]
154 This option is a synonym for the
155 .B \-E
156 option. Use
157 .B \-E
158 instead,
159 because it is POSIX compliant while this option is not. If
160 \fIeof-str\fR is omitted, there is no end of file string. If neither
161 .B \-E
162 nor
163 .B \-e
164 is used, no end of file string is used.
165 .TP
166 .B "\-\-help"
167 Print a summary of the options to
168 .B xargs
169 and exit.
170 .TP
171 .BI \-I " replace-str"
172 Replace occurrences of \fIreplace-str\fR in the initial-arguments with
173 names read from standard input. Also, unquoted blanks do not
174 terminate input items; instead the separator is the newline character.
175 Implies
176 .B \-x
177 and
178 .B \-L
179 1.
180 .TP
181 .PD 0
182 .BR "\-\-replace" [\fI=replace-str\fR]
183 .TP
184 .PD
185 .BR \-i "[\fIreplace-str\fR]"
186 This option is a synonym for
187 .BI \-I replace-str
188 if
189 .I replace-str
190 is specified. If the
191 .I replace-str
192 argument is missing, the effect is the same as
193 .BR \-I {}.
194 This option is deprecated; use
195 .B \-I
196 instead.
197 .TP
198 .BI \-L " max-lines"
199 Use at most \fImax-lines\fR nonblank input lines per command line.
200 Trailing blanks cause an input line to be logically continued on the
201 next input line. Implies
202 .BR \-x .
203 .TP
204 .PD 0
205 .BR \-\-max-lines "[=\fImax-lines\fR]"
206 .TP
207 .PD
208 .BR \-l "[\fImax-lines\fR]"
209 Synonym for the
210 .B \-L
211 option. Unlike
212 .BR \-L ,
213 the
214 .I max-lines
215 argument is optional. If
216 .I max-lines
217 is not specified, it defaults to one. The
218 .B \-l
219 option is deprecated since the POSIX standard specifies
220 .B \-L
221 instead.
222 .TP
223 .PD 0
224 .BR "\-\-max\-args" =\fImax-args\fR
225 .TP
226 .PD
227 .BI \-n " max-args"
228 Use at most \fImax-args\fR arguments per command line. Fewer than
229 .I max-args
230 arguments will be used if the size (see the
231 .B \-s
232 option) is exceeded, unless the
233 .B \-x
234 option is given, in which case
235 .B xargs will exit.
236 .TP
237 .PD 0
238 .B \-\-interactive
239 .TP
240 .PD
241 .B \-p
242 Prompt the user about whether to run each command line and read a line
243 from the terminal. Only run the command line if the response starts
244 with `y' or `Y'. Implies
245 .BR -t .
246 .TP
247 .PD 0
248 .B \-\-no\-run\-if\-empty
249 .TP
250 .PD
251 .B \-r
252 If the standard input does not contain any nonblanks, do not run the
253 command. Normally, the command is run once even if there is no input.
254 This option is a GNU extension.
255 .TP
256 .PD 0
257 .BR \-\-max\-chars "=\fImax-chars\fR"
258 .TP
259 .PD
260 .BI \-s " max-chars"
261 Use at most \fImax-chars\fR characters per command line, including the
262 command and initial-arguments and the terminating nulls at the ends of
263 the argument strings. The largest allowed value is system-dependent,
264 and is calculated as the argument length limit for exec, less the size
265 of your environment, less 2048 bytes of headroom. If this value is
266 more than 128KiB, 128Kib is used as the default value; otherwise, the
267 default value is the maximum. 1KiB is 1024 bytes.
268 .B xargs
269 automatically adapts to tighter constraints.
270 .TP
271 .PD 0
272 .B \-\-verbose
273 .TP
274 .PD
275 .B \-t
276 Print the command line on the standard error output before executing
277 it.
278 .TP
279 .B "\-\-version"
280 Print the version number of
281 .B xargs
282 and exit.
283 .TP
284 .B "\-\-show\\-limits"
285 Display the limits on the command-line length which are imposed by the
286 operating system,
287 .BR xargs '
288 choice of buffer size and the
289 .B \-s
290 option. Pipe the input from
291 .I /dev/null
292 (and perhaps specify
293 .BR --no-run-if-empty )
294 if you don't want
295 .B xargs
296 to do anything.
297 .TP
298 .PD 0
299 .B \-\-exit
300 .TP
301 .PD
302 .B \-x
303 Exit if the size (see the
304 .B \-s
305 option) is exceeded.
306 .TP
307 .PD 0
308 .BR \-\-max\-procs "=\fImax-procs\fR"
309 .TP
310 .PD
311 .BI \-P " max-procs"
312 Run up to
313 .I max-procs
314 processes at a time; the default is 1. If
315 .I max-procs
316 is 0,
317 .B xargs
318 will run as many processes as
319 possible at a time. Use the
320 .B \-n
321 option or the
322 .B \-L
323 option with
324 .BR \-P ;
325 otherwise chances are that only one exec will be done.
326 .SH "EXAMPLES"
327 .nf
328 .B find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
330 .fi
331 Find files named
332 .B core
333 in or below the directory
334 .B /tmp
335 and delete them. Note that this will work incorrectly if there are
336 any filenames containing newlines or spaces.
337 .P
338 .B find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
340 .fi
341 Find files named
342 .B core
343 in or below the directory
344 .B /tmp
345 and delete them, processing filenames in such a way that file or
346 directory names containing spaces or newlines are correctly handled.
348 .P
349 .B find /tmp \-depth \-name core \-type f \-delete
351 .fi
352 Find files named
353 .B core
354 in or below the directory
355 .B /tmp
356 and delete them, but more efficiently than in the previous example
357 (because we avoid the need to use
358 .BR fork (2)
359 and
360 .BR exec (2)
361 to launch
362 .B rm
363 and we don't need the extra
364 .B xargs
365 process).
367 .P
368 .nf
369 .B cut \-d: \-f1 < /etc/passwd | sort | xargs echo
371 .fi
372 Generates a compact listing of all the users on the system.
374 .P
375 .nf
376 .B xargs sh -c 'emacs \(dq$@\(dq < /dev/tty' emacs
378 .fi
379 Launches the minimum number of copies of Emacs needed, one after the
380 other, to edit the files listed on
381 .BR xargs '
382 standard input. This example achieves the same effect as BSD's
383 .B -o
384 option, but in a more flexible and portable way.
388 .SH "EXIT STATUS"
389 .B xargs
390 exits with the following status:
391 .nf
392 0 if it succeeds
393 123 if any invocation of the command exited with status 1-125
394 124 if the command exited with status 255
395 125 if the command is killed by a signal
396 126 if the command cannot be run
397 127 if the command is not found
398 1 if some other error occurred.
399 .fi
400 .P
401 Exit codes greater than 128 are used by the shell to indicate that
402 a program died due to a fatal signal.
403 .SH "STANDARDS CONFORMANCE"
404 As of GNU xargs version 4.2.9, the default behaviour of
405 .B xargs
406 is not to have a logical end-of-file marker. POSIX (IEEE Std 1003.1,
407 2004 Edition) allows this.
408 .P
409 The \-l and \-i options appear in the 1997 version of the POSIX
410 standard, but do not appear in the 2004 version of the standard.
411 Therefore you should use \-L and \-I instead, respectively.
412 .P
413 The POSIX standard allows implementations to have a limit on the size
414 of arguments to the
415 .B exec
416 functions. This limit could be as low as 4096 bytes including the size of the
417 environment. For scripts to be portable, they must not rely on a
418 larger value. However, I know of no implementation whose actual limit
419 is that small. The
420 .B \-\-show\-limits
421 option can be used to discover the actual limits in force on the
422 current system.
425 .SH "SEE ALSO"
426 \fBfind\fP(1), \fBlocate\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1),
427 \fBfork\fP(2), \fBexecvp\fP(3),
428 \fBFinding Files\fP (on-line in Info, or printed)
429 .SH "BUGS"
430 The
431 .B \-L
432 option is incompatible with the
433 .B \-I
434 option, but perhaps should not be.
435 .P
436 It is not possible for
437 .B xargs
438 to be used securely, since there will always be a time gap between the
439 production of the list of input files and their use in the commands
440 that
441 .B xargs
442 issues. If other users have access to the system, they can manipulate
443 the filesystem during this time window to force the action of the
444 commands
445 .B xargs
446 runs to apply to files that you didn't intend. For a more detailed
447 discussion of this and related problems, please refer to the
448 ``Security Considerations'' chapter in the findutils Texinfo
449 documentation. The
450 .B \-execdir
451 option of
452 .B find
453 can often be used as a more secure alternative.
455 When you use the
456 .B \-I
457 option, each line read from the input is buffered
458 internally. This means that there is an upper limit on the length
459 of input line that
460 .B xargs
461 will accept when used with the
462 .B \-I
463 option. To work around this
464 limitation, you can use the
465 .B \-s
466 option to increase the amount of
467 buffer space that
468 .B xargs
469 uses, and you can also use an extra invocation of
470 .B xargs
471 to ensure that very long lines do not occur.
472 For example:
473 .P
474 .B somecommand | xargs \-s 50000 echo | xargs \-I '{}' \-s 100000 rm '{}'
475 .P
476 Here, the first invocation of
477 .B xargs
478 has no input line length limit
479 because it doesn't use the
480 .B \-i
481 option. The second invocation of
482 .B xargs
483 does have such a limit, but we have ensured that the it never encounters
484 a line which is longer than it can handle. This is not an ideal
485 solution. Instead, the
486 .B \-i
487 option should not impose a line length
488 limit, which is why this discussion appears in the BUGS section.
489 The problem doesn't occur with the output of
490 .BR find (1)
491 because it emits just one filename per line.
492 .P
493 The best way to report a bug is to use the form at
494 http://savannah.gnu.org/bugs/?group=findutils.
495 The reason for this is that you will then be able to track progress in
496 fixing the problem. Other comments about \fBxargs\fP(1) and about
497 the findutils package in general can be sent to the
498 .I bug\-findutils
499 mailing list. To join the list, send email to
500 .IR bug\-findutils\-request@gnu.org .