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\-\-interactive\fR]
29 [\fB\-\-no\-run\-if\-empty\fR]
30 [\fB\-\-arg\-file\fR=\fIfile\fR]
31 [\fB\-\-show\-limits\fR]
34 [\fIcommand\fR [\fIinitial-arguments\fR]]
38 documents the GNU version of
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,
47 one or more times with any
49 followed by items read from standard input. Blank lines on the
50 standard input are ignored.
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
56 In these situations it is better to use the
59 prevents such problems. When using this option you will need to
60 ensure that the program which produces the input for
62 also uses a null character as a separator. If that program is
67 option does this for you.
69 If any invocation of the command exits with a status of 255,
71 will stop immediately without reading any further input. An error
72 message is issued on stderr when this happens.
76 .BI "\-\-arg\-file=" file
82 instead of standard input. If you use this option, stdin remains
83 unchanged when commands are run. Otherwise, stdin is redirected
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.
102 .BI "\-\-delimiter=" 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
113 where this is possible. The specified
114 delimiter may be a single character, a C-style character escape such
117 or an octal or hexadecimal escape code. Octal and hexadecimal
118 escape codes are understood as for the
120 command. Multibyte characters are not supported.
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.
130 is used, no end of file string is used.
133 .BR "\-\-eof" [\fI=eof-str\fR]
136 .BR \-e [ \fIeof-str\fR]
137 This option is a synonym for the
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
147 is used, no end of file string is used.
150 Print a summary of the options to
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.
165 .BR "\-\-replace" [\fI=replace-str\fR]
168 .BR \-i "[\fIreplace-str\fR]"
169 This option is a synonym for
173 is specified, and for
175 otherwise. This option is deprecated; use
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
186 .BR \-\-max-lines "[=\fImax-lines\fR]"
189 .BR \-l "[\fImax-lines\fR]"
196 argument is optional. If
198 is not specified, it defaults to one. The
200 option is deprecated since the POSIX standard specifies
205 .BR "\-\-max\-args" =\fImax-args\fR
209 Use at most \fImax-args\fR arguments per command line. Fewer than
211 arguments will be used if the size (see the
213 option) is exceeded, unless the
215 option is given, in which case
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
229 .B \-\-no\-run\-if\-empty
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.
238 .BR \-\-max\-chars "=\fImax-chars\fR"
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.
255 Print the command line on the standard error output before executing
259 Print the version number of
263 .B "\-\-show\\-limits"
264 Display the limits on the command-line length which are imposed by the
267 choice of buffer size and the
269 option. Pipe the input from
272 .BR --no-run-if-empty )
282 Exit if the size (see the
287 .BR \-\-max\-procs "=\fImax-procs\fR"
293 processes at a time; the default is 1. If
297 will run as many processes as
298 possible at a time. Use the
302 otherwise chances are that only one exec will be done.
305 .B find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
310 in or below the directory
312 and delete them. Note that this will work incorrectly if there are
313 any filenames containing newlines or spaces.
315 .B find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
320 in or below the directory
322 and delete them, processing filenames in such a way that file or
323 directory names containing spaces or newlines are correctly handled.
326 .B cut \-d: \-f1 < /etc/passwd | sort | xargs echo
329 Generates a compact listing of all the users on the system.
332 exits with the following status:
335 123 if any invocation of the command exited with status 1-125
336 124 if the command exited with status 255
337 125 if the command is killed by a signal
338 126 if the command cannot be run
339 127 if the command is not found
340 1 if some other error occurred.
343 Exit codes greater than 128 are used by the shell to indicate that
344 a program died due to a fatal signal.
345 .SH "STANDARDS CONFORMANCE"
346 As of GNU xargs version 4.2.9, the default behaviour of
348 is not to have a logical end-of-file marker. POSIX (IEEE Std 1003.1,
349 2004 Edition) allows this.
351 The \-l and \-i options appear in the 1997 version of the POSIX
352 standard, but do not appear in the 2004 version of the standard.
353 Therefore you should use \-L and \-I instead, respectively.
355 The POSIX stadard allows implementations to have a limit on the size
358 functions. This limit could be as low as 4096 bytes including the size of the
359 environment. For scripts to be portable, they must not rely on a
360 larger value. However, I know of no implementation whose actual limit
363 option can be used to discover the actual limits in force on the
368 \fBfind\fP(1), \fBlocate\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1),
369 \fBFinding Files\fP (on-line in Info, or printed)
373 option is incompatible with the
375 option, but perhaps should not be.
377 It is not possible for
379 to be used securely, since there will always be a time gap between the
380 production of the list of input files and their use in the commands
383 issues. If other users have access to the system, they can manipulate
384 the filesystem during this time window to force the action of the
387 runs to apply to files that you didn't intend. For a more detailed
388 discussion of this and related problems, please refer to the
389 ``Security Considerations'' chapter in the findutils Texinfo
394 can often be used as a more secure alternative.
398 option, each line read from the input is buffered
399 internally. This means that there is an upper limit on the length
402 will accept when used with the
404 option. To work around this
405 limitation, you can use the
407 option to increase the amount of
410 uses, and you can also use an extra invocation of
412 to ensure that very long lines do not occur.
415 .B somecommand | xargs \-s 50000 echo | xargs \-I '{}' \-s 100000 rm '{}'
417 Here, the first invocation of
419 has no input line length limit
420 because it doesn't use the
422 option. The second invocation of
424 does have such a limit, but we have ensured that the it never encounters
425 a line which is longer than it can handle. This is not an ideal
426 solution. Instead, the
428 option should not impose a line length
429 limit, which is why this discussion appears in the BUGS section.
430 The problem doesn't occur with the output of
432 because it emits just one filename per line.
434 The best way to report a bug is to use the form at
435 http://savannah.gnu.org/bugs/?group=findutils.
436 The reason for this is that you will then be able to track progress in
437 fixing the problem. Other comments about \fBxargs\fP(1) and about
438 the findutils package in general can be sent to the
440 mailing list. To join the list, send email to
441 .IR bug\-findutils\-request@gnu.org .