1 .TH XARGS 1 \" -*- nroff -*-
3 xargs \- build and execute command lines from standard input
9 [\fB\-e\fR[\fIeof-str\fR]]
10 [\fB\-\-eof\fR[=\fIeof-str\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\-\-process\-slot\-var\fR=\fIname\fR]
27 [\fB\-\-interactive\fR]
30 [\fB\-\-no\-run\-if\-empty\fR]
31 [\fB\-\-arg\-file\fR=\fIfile\fR]
32 [\fB\-\-show\-limits\fR]
35 [\fIcommand\fR [\fIinitial-arguments\fR]]
39 documents the GNU version of
42 reads items from the standard input, delimited by blanks (which can be
43 protected with double or single quotes or a backslash) or newlines,
48 one or more times with any
50 followed by items read from standard input. Blank lines on the
51 standard input are ignored.
55 is built up until it reaches a system-defined limit (unless the
59 options are used). The specified
61 will be invoked as many times as necessary to use up the list of input
62 items. In general, there will be many fewer invocations of
64 than there were items in the input. This will normally have
65 significant performance benefits. Some commands can usefully be
66 executed in parallel too; see the
70 Because Unix filenames can contain blanks and newlines, this default
71 behaviour is often problematic; filenames containing blanks
72 and/or newlines are incorrectly processed by
74 In these situations it is better to use the
77 prevents such problems. When using this option you will need to
78 ensure that the program which produces the input for
80 also uses a null character as a separator. If that program is
85 option does this for you.
87 If any invocation of the command exits with a status of 255,
89 will stop immediately without reading any further input. An error
90 message is issued on stderr when this happens.
95 Input items are terminated by a null character instead of by
96 whitespace, and the quotes and backslash are not special (every
97 character is taken literally). Disables the end of file string, which
98 is treated like any other argument. Useful when input items might
99 contain white space, quote marks, or backslashes. The GNU find
100 \-print0 option produces input suitable for this mode.
104 .BI "\-a " file ", \-\-arg\-file=" file
107 instead of standard input. If you use this option, stdin remains
108 unchanged when commands are run. Otherwise, stdin is redirected
114 .BI "\-\-delimiter=" delim ", \-d" " delim"
115 Input items are terminated by the specified character. The specified
116 delimiter may be a single character, a C-style character escape such
119 or an octal or hexadecimal escape code. Octal and hexadecimal
120 escape codes are understood as for the
122 command. Multibyte characters are not supported.
123 When processing the input, quotes and backslash are not special; every
124 character in the input is taken literally. The
126 option disables any end-of-file string, which is treated like any
127 other argument. You can use this option when the input consists of
128 simply newline-separated items, although it is almost always better to
129 design your program to use
131 where this is possible.
135 Set the end of file string to \fIeof-str\fR. If the end of file
136 string occurs as a line of input, the rest of the input is ignored.
141 is used, no end of file string is used.
144 .BR \-e "[\fIeof-str\fR], " "\-\-eof" [\fI=eof-str\fR]
145 This option is a synonym for the
150 because it is POSIX compliant while this option is not. If
151 \fIeof-str\fR is omitted, there is no end of file string. If neither
155 is used, no end of file string is used.
157 .BI \-I " replace-str"
158 Replace occurrences of \fIreplace-str\fR in the initial-arguments with
159 names read from standard input. Also, unquoted blanks do not
160 terminate input items; instead the separator is the newline character.
168 .BR \-i "[\fIreplace-str\fR], " "\-\-replace" [\fI=replace-str\fR]
169 This option is a synonym for
175 argument is missing, the effect is the same as
177 This option is deprecated; use
182 Use at most \fImax-lines\fR nonblank input lines per command line.
183 Trailing blanks cause an input line to be logically continued on the
184 next input line. Implies
188 .BR \-l "[\fImax-lines\fR], " \-\-max-lines "[=\fImax-lines\fR]"
195 argument is optional. If
197 is not specified, it defaults to one. The
199 option is deprecated since the POSIX standard specifies
204 .BI \-n " max-args\fB, \fI" "\-\-max\-args" \fR=\fImax-args
205 Use at most \fImax-args\fR arguments per command line. Fewer than
207 arguments will be used if the size (see the
209 option) is exceeded, unless the
211 option is given, in which case
215 .BI \-P " max-procs\fR, \fI" \-\-max\-procs "\fR=\fImax-procs"
218 processes at a time; the default is 1. If
222 will run as many processes as
223 possible at a time. Use the
229 otherwise chances are that only one exec will be done.
234 a SIGUSR1 signal to increase the number of commands to run simultaneously,
235 or a SIGUSR2 to decrease the number. You cannot decrease it below 1.
237 never terminates its commands; when asked to decrease, it merely
238 waits for more than one existing command to terminate before starting
242 that it is up to the called processes to properly manage parallel
243 access to shared resources. For example, if more than one of them
244 tries to print to stdout, the ouptut will be produced in an
245 indeterminate order (and very likely mixed up) unless the processes
246 collaborate in some way to prevent this. Using some kind of locking
247 scheme is one way to prevent such problems. In general, using a
248 locking scheme will help ensure correct output but reduce performance.
249 If you don't want to tolerate the performance difference, simply
250 arrange for each process to produce a separate output file (or
251 otherwise use separate resources).
254 .B \-p, \-\-interactive
255 Prompt the user about whether to run each command line and read a line
256 from the terminal. Only run the command line if the response starts
257 with `y' or `Y'. Implies
261 .BR \-\-process\-slot\-var "=\fIname\fR"
262 Set the environment variable
264 to a unique value in each running child process. Values are reused
265 once child processes exit. This can be used in a rudimentary load
266 distribution scheme, for example.
269 .B \-r, \-\-no\-run\-if\-empty
270 If the standard input does not contain any nonblanks, do not run the
271 command. Normally, the command is run once even if there is no input.
272 This option is a GNU extension.
275 .BI -s " max-chars\fR, \fI" \-\-max\-chars "=\fImax-chars\fR"
276 Use at most \fImax-chars\fR characters per command line, including the
277 command and initial-arguments and the terminating nulls at the ends of
278 the argument strings. The largest allowed value is system-dependent,
279 and is calculated as the argument length limit for exec, less the size
280 of your environment, less 2048 bytes of headroom. If this value is
281 more than 128KiB, 128Kib is used as the default value; otherwise, the
282 default value is the maximum. 1KiB is 1024 bytes.
284 automatically adapts to tighter constraints.
286 .B "\-\-show\\-limits"
287 Display the limits on the command-line length which are imposed by the
290 choice of buffer size and the
292 option. Pipe the input from
295 .BR --no-run-if-empty )
301 Print the command line on the standard error output before executing
306 Exit if the size (see the
311 Print a summary of the options to
316 Print the version number of
321 .B find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
326 in or below the directory
328 and delete them. Note that this will work incorrectly if there are
329 any filenames containing newlines or spaces.
331 .B find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
336 in or below the directory
338 and delete them, processing filenames in such a way that file or
339 directory names containing spaces or newlines are correctly handled.
342 .B find /tmp \-depth \-name core \-type f \-delete
347 in or below the directory
349 and delete them, but more efficiently than in the previous example
350 (because we avoid the need to use
356 and we don't need the extra
362 .B cut \-d: \-f1 < /etc/passwd | sort | xargs echo
365 Generates a compact listing of all the users on the system.
369 .B xargs sh -c 'emacs \(dq$@\(dq < /dev/tty' emacs
372 Launches the minimum number of copies of Emacs needed, one after the
373 other, to edit the files listed on
375 standard input. This example achieves the same effect as BSD's
377 option, but in a more flexible and portable way.
383 exits with the following status:
386 123 if any invocation of the command exited with status 1-125
387 124 if the command exited with status 255
388 125 if the command is killed by a signal
389 126 if the command cannot be run
390 127 if the command is not found
391 1 if some other error occurred.
394 Exit codes greater than 128 are used by the shell to indicate that
395 a program died due to a fatal signal.
396 .SH "STANDARDS CONFORMANCE"
397 As of GNU xargs version 4.2.9, the default behaviour of
399 is not to have a logical end-of-file marker. POSIX (IEEE Std 1003.1,
400 2004 Edition) allows this.
402 The \-l and \-i options appear in the 1997 version of the POSIX
403 standard, but do not appear in the 2004 version of the standard.
404 Therefore you should use \-L and \-I instead, respectively.
406 The POSIX standard allows implementations to have a limit on the size
409 functions. This limit could be as low as 4096 bytes including the size of the
410 environment. For scripts to be portable, they must not rely on a
411 larger value. However, I know of no implementation whose actual limit
414 option can be used to discover the actual limits in force on the
419 \fBfind\fP(1), \fBlocate\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1),
420 \fBfork\fP(2), \fBexecvp\fP(3),
421 \fBkill\fP(1), \fBsignal\fP(7),
423 The full documentation for
425 is maintained as a Texinfo manual. If the
429 programs are properly installed at your site, the command
431 should give you access to the complete manual.
436 option is incompatible with the
438 option, but perhaps should not be.
440 It is not possible for
442 to be used securely, since there will always be a time gap between the
443 production of the list of input files and their use in the commands
446 issues. If other users have access to the system, they can manipulate
447 the filesystem during this time window to force the action of the
450 runs to apply to files that you didn't intend. For a more detailed
451 discussion of this and related problems, please refer to the
452 ``Security Considerations'' chapter in the findutils Texinfo
457 can often be used as a more secure alternative.
461 option, each line read from the input is buffered
462 internally. This means that there is an upper limit on the length
465 will accept when used with the
467 option. To work around this
468 limitation, you can use the
470 option to increase the amount of
473 uses, and you can also use an extra invocation of
475 to ensure that very long lines do not occur.
478 .B somecommand | xargs \-s 50000 echo | xargs \-I '{}' \-s 100000 rm '{}'
480 Here, the first invocation of
482 has no input line length limit
483 because it doesn't use the
485 option. The second invocation of
487 does have such a limit, but we have ensured that the it never encounters
488 a line which is longer than it can handle. This is not an ideal
489 solution. Instead, the
491 option should not impose a line length
492 limit, which is why this discussion appears in the BUGS section.
493 The problem doesn't occur with the output of
495 because it emits just one filename per line.
497 The best way to report a bug is to use the form at
498 http://savannah.gnu.org/bugs/?group=findutils.
499 The reason for this is that you will then be able to track progress in
500 fixing the problem. Other comments about \fBxargs\fP(1) and about
501 the findutils package in general can be sent to the
503 mailing list. To join the list, send email to
504 .IR bug\-findutils\-request@gnu.org .