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.
232 is running, you can send its process a SIGUSR1 signal to increase the
233 number of commands to run simultaneously, or a SIGUSR2 to decrease the
234 number. You cannot increase it above an implementation-defined limit
235 (which is shown with \-\-show-limits). You cannot decrease it below
238 never terminates its commands; when asked to decrease, it merely
239 waits for more than one existing command to terminate before starting
243 that it is up to the called processes to properly manage parallel
244 access to shared resources. For example, if more than one of them
245 tries to print to stdout, the ouptut will be produced in an
246 indeterminate order (and very likely mixed up) unless the processes
247 collaborate in some way to prevent this. Using some kind of locking
248 scheme is one way to prevent such problems. In general, using a
249 locking scheme will help ensure correct output but reduce performance.
250 If you don't want to tolerate the performance difference, simply
251 arrange for each process to produce a separate output file (or
252 otherwise use separate resources).
255 .B \-p, \-\-interactive
256 Prompt the user about whether to run each command line and read a line
257 from the terminal. Only run the command line if the response starts
258 with `y' or `Y'. Implies
262 .BR \-\-process\-slot\-var "=\fIname\fR"
263 Set the environment variable
265 to a unique value in each running child process. Values are reused
266 once child processes exit. This can be used in a rudimentary load
267 distribution scheme, for example.
270 .B \-r, \-\-no\-run\-if\-empty
271 If the standard input does not contain any nonblanks, do not run the
272 command. Normally, the command is run once even if there is no input.
273 This option is a GNU extension.
276 .BI -s " max-chars\fR, \fI" \-\-max\-chars "=\fImax-chars\fR"
277 Use at most \fImax-chars\fR characters per command line, including the
278 command and initial-arguments and the terminating nulls at the ends of
279 the argument strings. The largest allowed value is system-dependent,
280 and is calculated as the argument length limit for exec, less the size
281 of your environment, less 2048 bytes of headroom. If this value is
282 more than 128KiB, 128Kib is used as the default value; otherwise, the
283 default value is the maximum. 1KiB is 1024 bytes.
285 automatically adapts to tighter constraints.
287 .B "\-\-show\\-limits"
288 Display the limits on the command-line length which are imposed by the
291 choice of buffer size and the
293 option. Pipe the input from
296 .BR --no-run-if-empty )
302 Print the command line on the standard error output before executing
307 Exit if the size (see the
312 Print a summary of the options to
317 Print the version number of
322 .B find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
327 in or below the directory
329 and delete them. Note that this will work incorrectly if there are
330 any filenames containing newlines or spaces.
332 .B find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
337 in or below the directory
339 and delete them, processing filenames in such a way that file or
340 directory names containing spaces or newlines are correctly handled.
343 .B find /tmp \-depth \-name core \-type f \-delete
348 in or below the directory
350 and delete them, but more efficiently than in the previous example
351 (because we avoid the need to use
357 and we don't need the extra
363 .B cut \-d: \-f1 < /etc/passwd | sort | xargs echo
366 Generates a compact listing of all the users on the system.
370 .B xargs sh -c 'emacs \(dq$@\(dq < /dev/tty' emacs
373 Launches the minimum number of copies of Emacs needed, one after the
374 other, to edit the files listed on
376 standard input. This example achieves the same effect as BSD's
378 option, but in a more flexible and portable way.
384 exits with the following status:
387 123 if any invocation of the command exited with status 1-125
388 124 if the command exited with status 255
389 125 if the command is killed by a signal
390 126 if the command cannot be run
391 127 if the command is not found
392 1 if some other error occurred.
395 Exit codes greater than 128 are used by the shell to indicate that
396 a program died due to a fatal signal.
397 .SH "STANDARDS CONFORMANCE"
398 As of GNU xargs version 4.2.9, the default behaviour of
400 is not to have a logical end-of-file marker. POSIX (IEEE Std 1003.1,
401 2004 Edition) allows this.
403 The \-l and \-i options appear in the 1997 version of the POSIX
404 standard, but do not appear in the 2004 version of the standard.
405 Therefore you should use \-L and \-I instead, respectively.
407 The POSIX standard allows implementations to have a limit on the size
410 functions. This limit could be as low as 4096 bytes including the size of the
411 environment. For scripts to be portable, they must not rely on a
412 larger value. However, I know of no implementation whose actual limit
415 option can be used to discover the actual limits in force on the
420 \fBfind\fP(1), \fBlocate\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1),
421 \fBfork\fP(2), \fBexecvp\fP(3),
422 \fBkill\fP(1), \fBsignal\fP(7),
424 The full documentation for
426 is maintained as a Texinfo manual. If the
430 programs are properly installed at your site, the command
432 should give you access to the complete manual.
437 option is incompatible with the
439 option, but perhaps should not be.
441 It is not possible for
443 to be used securely, since there will always be a time gap between the
444 production of the list of input files and their use in the commands
447 issues. If other users have access to the system, they can manipulate
448 the filesystem during this time window to force the action of the
451 runs to apply to files that you didn't intend. For a more detailed
452 discussion of this and related problems, please refer to the
453 ``Security Considerations'' chapter in the findutils Texinfo
458 can often be used as a more secure alternative.
462 option, each line read from the input is buffered
463 internally. This means that there is an upper limit on the length
466 will accept when used with the
468 option. To work around this
469 limitation, you can use the
471 option to increase the amount of
474 uses, and you can also use an extra invocation of
476 to ensure that very long lines do not occur.
479 .B somecommand | xargs \-s 50000 echo | xargs \-I '{}' \-s 100000 rm '{}'
481 Here, the first invocation of
483 has no input line length limit
484 because it doesn't use the
486 option. The second invocation of
488 does have such a limit, but we have ensured that the it never encounters
489 a line which is longer than it can handle. This is not an ideal
490 solution. Instead, the
492 option should not impose a line length
493 limit, which is why this discussion appears in the BUGS section.
494 The problem doesn't occur with the output of
496 because it emits just one filename per line.
498 The best way to report a bug is to use the form at
499 http://savannah.gnu.org/bugs/?group=findutils.
500 The reason for this is that you will then be able to track progress in
501 fixing the problem. Other comments about \fBxargs\fP(1) and about
502 the findutils package in general can be sent to the
504 mailing list. To join the list, send email to
505 .IR bug\-findutils\-request@gnu.org .
OSDN Git Service
