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