Debian Codegraph @

upstream/debian-unstable/man1/xargs.1

raw
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 [\fIoptions\fR]
8 [\fIcommand\fR [\fIinitial-arguments\fR]]
9 .hy
10 .
11 .SH DESCRIPTION
12 This manual page
13 documents the GNU version of
14 .BR xargs .
15 .B xargs
16 reads items from the standard input, delimited by blanks (which can be
17 protected with double or single quotes or a backslash) or newlines,
18 and executes the
19 .I command
20 (default is
21 .IR echo )
22 one or more times with any
23 .I initial-arguments
24 followed by items read from standard input.
25 Blank lines on the standard input are ignored.
26 .P
27 The command line for
28 .I command
29 is built up until it reaches a system-defined limit (unless the
30 .B \-n
31 and
32 .B \-L
33 options are used).
34 The specified
35 .I command
36 will be invoked as many times as necessary to use up the list of input items.
37 In general, there will be many fewer invocations of
38 .I command
39 than there were items in the input.
40 This will normally have significant performance benefits.
41 Some commands can usefully be executed in parallel too; see the
42 .B \-P
43 option.
44 .P
45 Because Unix filenames can contain blanks and newlines, this default
46 behaviour is often problematic; filenames containing blanks
47 and/or newlines are incorrectly processed by
48 .BR xargs .
49 In these situations it is better to use the
50 .B \-0
51 option, which
52 prevents such problems.
53 When using this option you will need to
54 ensure that the program which produces the input for
55 .B xargs
56 also uses a null character as a separator.
57 If that program is GNU
58 .B find
59 for example, the
60 .B \-print0
61 option does this for you.
62 .P
63 If any invocation of the command exits with a status of 255,
64 .B xargs
65 will stop immediately without reading any further input.
66 An error message is issued on stderr when this happens.
67 .
68 .SH OPTIONS
69 .TP
70 .B \-0, \-\-null
71 Input items are terminated by a null character instead of by
72 whitespace, and the quotes and backslash are not special (every
73 character is taken literally).
74 Disables the end-of-file string, which is treated like any other argument.
75 Useful when input items might contain white space, quote marks, or backslashes.
76 The GNU find \-print0 option produces input suitable for this mode.
77
78 .TP
79 .BI "\-a " file ", \-\-arg\-file=" file
80 Read items from
81 .I file
82 instead of standard input.
83 If you use this option, stdin remains unchanged when commands are run.
84 Otherwise, stdin is redirected from
85 .IR /dev/null .
86
87 .TP
88 .BI "\-\-delimiter=" delim ", \-d" " delim"
89 Input items are terminated by the specified character.
90 The specified delimiter may be a single character, a C-style character escape such
91 as
92 .BR \en ,
93 or an octal or hexadecimal escape code.
94 Octal and hexadecimal escape codes are understood as for the
95 .B printf
96 command.
97 Multibyte characters are not supported.
98 When processing the input, quotes and backslash are not special;
99 every character in the input is taken literally.
100 The
101 .B \-d
102 option disables any end-of-file string, which is treated like any
103 other argument.
104 You can use this option when the input consists of
105 simply newline-separated items, although it is almost always better to
106 design your program to use
107 .B \-\-null
108 where this is possible.
109
110 .TP
111 .BI \-E " eof-str"
112 Set the end-of-file string to \fIeof-str\fR.
113 If the end-of-file
114 string occurs as a line of input, the rest of the input is ignored.
115 If neither
116 .B \-E
117 nor
118 .B \-e
119 is used, no end-of-file string is used.
120 .TP
121 .BR \-e "[\fIeof-str\fR], " "\-\-eof" [\fI=eof-str\fR]
122 This option is a synonym for the
123 .B \-E
124 option.
125 Use
126 .B \-E
127 instead,
128 because it is POSIX compliant while this option is not.
129 If \fIeof-str\fR is omitted, there is no end-of-file string.
130 If neither
131 .B \-E
132 nor
133 .B \-e
134 is used, no end-of-file string is used.
135 .TP
136 .BI \-I " replace-str"
137 Replace occurrences of \fIreplace-str\fR in the initial-arguments with
138 names read from standard input.
139 Also, unquoted blanks do not
140 terminate input items; instead the separator is the newline character.
141 Implies
142 .B \-x
143 and
144 .B \-L
145 1.
146 .TP
147 .BR \-i "[\fIreplace-str\fR], " "\-\-replace" [\fI=replace-str\fR]
148 This option is a synonym for
149 .BI \-I replace-str
150 if
151 .I replace-str
152 is specified.
153 If the
154 .I replace-str
155 argument is missing, the effect is the same as
156 .BR \-I {}.
157 The
158 .B \-i
159 option is deprecated; use
160 .B \-I
161 instead.
162 .TP
163 .BI \-L " max-lines"
164 Use at most \fImax-lines\fR nonblank input lines per command line.
165 Trailing blanks cause an input line to be logically continued on the
166 next input line.
167 Implies
168 .BR \-x .
169 .TP
170 .BR \-l "[\fImax-lines\fR], " \-\-max-lines "[=\fImax-lines\fR]"
171 Synonym for the
172 .B \-L
173 option.
174 Unlike
175 .BR \-L ,
176 the
177 .I max-lines
178 argument is optional.
179 If
180 .I max-lines
181 is not specified, it defaults to one.
182 The
183 .B \-l
184 option is deprecated since the POSIX standard specifies
185 .B \-L
186 instead.
187 .TP
188 .BI \-n " max-args\fR, \fI" "\-\-max\-args" \fR=\fImax-args
189 Use at most \fImax-args\fR arguments per command line.
190 Fewer than
191 .I max-args
192 arguments will be used if the size (see the
193 .B \-s
194 option) is exceeded, unless the
195 .B \-x
196 option is given, in which case
197 .B xargs
198 will exit.
199 .TP
200 .BI \-P " max-procs\fR, \fI" \-\-max\-procs "\fR=\fImax-procs"
201 Run up to
202 .I max-procs
203 processes at a time; the default is 1.
204 If
205 .I max-procs
206 is 0,
207 .B xargs
208 will run as many processes as possible at a time.
209 Use the
210 .B \-n
211 option or the
212 .B \-L
213 option with
214 .BR \-P ;
215 otherwise chances are that only one exec will be done.
216 While
217 .B xargs
218 is running, you can send its process a SIGUSR1 signal to increase the
219 number of commands to run simultaneously, or a SIGUSR2 to decrease the
220 number.
221 You cannot increase it above an implementation-defined limit
222 (which is shown with \-\-show-limits).
223 You cannot decrease it below 1.
224 .B xargs
225 never terminates its commands; when asked to decrease, it merely
226 waits for more than one existing command to terminate before starting
227 another.
228 .B xargs
229 always waits for all child processes to exit before exiting itself
230 (but see BUGS).
231
232 If you do not use the
233 .B \-P
234 option,
235 .B xargs
236 will not handle the SIGUSR1 and SIGUSR2 signals, meaning that they
237 will terminate the program (unless they were blocked in the parent
238 process before
239 .B xargs
240 was started).
241
242 .B Please note
243 that it is up to the called processes to properly manage parallel
244 access to shared resources.
245 For example, if more than one of them tries to print to stdout,
246 the output will be produced in an indeterminate order (and very
247 likely mixed up) unless the processes collaborate in some way to
248 prevent this.
249 Using some kind of locking scheme is one way to prevent such problems.
250 In general, using a locking scheme will help ensure correct output
251 but reduce performance.
252 If you don't want to tolerate the performance difference, simply
253 arrange for each process to produce a separate output file (or
254 otherwise use separate resources).
255 .TP
256 .B \-o, \-\-open\-tty
257 Reopen stdin as
258 .I /dev/tty
259 in the child process before executing the command.
260 This is useful if you want
261 .B xargs
262 to run an interactive application.
263 .TP
264 .B \-p, \-\-interactive
265 Prompt the user about whether to run each command line and read a line
266 from the terminal.
267 Only run the command line if the response starts with `y' or `Y'.
268 Implies
269 .BR \-t .
270 .TP
271 .BR \-\-process\-slot\-var "=\fIname\fR"
272 Set the environment variable
273 .I name
274 to a unique value in each running child process.
275 Values are reused once child processes exit.
276 This can be used in a rudimentary load distribution scheme, for example.
277 .TP
278 .B \-r, \-\-no\-run\-if\-empty
279 If the standard input does not contain any nonblanks, do not run the
280 command.
281 Normally, the command is run once even if there is no input.
282 This option is a GNU extension.
283 .TP
284 .BI \-s " max-chars\fR, \fI" \-\-max\-chars "=\fImax-chars\fR"
285 Use at most \fImax-chars\fR characters per command line, including the
286 command and initial-arguments and the terminating nulls at the ends of
287 the argument strings.
288 The largest allowed value is system-dependent, and is calculated as the
289 argument length limit for exec, less the size of your environment,
290 less 2048\~bytes of headroom.
291 If this value is more than 128\~KiB, 128\~KiB is used as the default value;
292 otherwise, the default value is the maximum.
293 1\~KiB is 1024 bytes.
294 .B xargs
295 automatically adapts to tighter constraints.
296 .TP
297 .B "\-\-show\-limits"
298 Display the limits on the command-line length which are imposed by the
299 operating system,
300 .BR xargs '
301 choice of buffer size and the
302 .B \-s
303 option.
304 Pipe the input from
305 .I /dev/null
306 (and perhaps specify
307 .BR \-\-no-run-if-empty )
308 if you don't want
309 .B xargs
310 to do anything.
311 .TP
312 .B \-t, \-\-verbose
313 Print the command line on the standard error output before executing
314 it.
315 .TP
316 .B \-x, \-\-exit
317 Exit if the size (see the
318 .B \-s
319 option) is exceeded.
320 .TP
321 .B "\-\-"
322 Delimit the option list.
323 Later arguments, if any, are treated as operands even if they begin with
324 .IR \- .
325 For example,
326 .B xargs \-\- \-\-help
327 runs the command
328 .I \-\-help
329 (found in
330 .IR PATH )
331 instead of printing the usage text, and
332 .B xargs \-\- \-\-mycommand
333 runs the command
334 .I \-\-mycommand
335 instead of rejecting this as unrecognized option.
336 .TP
337 .B "\-\-help"
338 Print a summary of the options to
339 .B xargs
340 and exit.
341 .TP
342 .B "\-\-version"
343 Print the version number of
344 .B xargs
345 and exit.
346 .PP
347 The options
348 .B \-\-max-lines
349 (\fB\-L\fP, \fB\-l\fP),
350 .B \-\-replace
351 (\fB\-I\fP, \fB\-i\fP)
352 and
353 .B \-\-max-args
354 (\fB\-n\fP)
355 are mutually exclusive.
356 If some of them are specified at the same time, then
357 .B xargs
358 will generally use the option specified last on the command line,
359 i.e., it will reset the value of the offending option (given before)
360 to its default value.
361 Additionally,
362 .B xargs
363 will issue a warning diagnostic on
364 .IR stderr .
365 The exception to this rule is that the special
366 .I max-args
367 value
368 .I 1
369 ('\fB\-n\fP\fI1\fP')
370 is ignored after the
371 .B \-\-replace
372 option and its aliases
373 .B \-I
374 and
375 .BR \-i ,
376 because it would not actually conflict.
377
378 .
379 .SH "EXAMPLES"
380 .nf
381 .B find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
382
383 .fi
384 Find files named
385 .B core
386 in or below the directory
387 .B /tmp
388 and delete them.
389 Note that this will work incorrectly if there are
390 any filenames containing newlines or spaces.
391 .P
392 .B find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
393
394 Find files named
395 .B core
396 in or below the directory
397 .B /tmp
398 and delete them, processing filenames in such a way that file or
399 directory names containing spaces or newlines are correctly handled.
400
401 .P
402 .B find /tmp \-depth \-name core \-type f \-delete
403
404 Find files named
405 .B core
406 in or below the directory
407 .B /tmp
408 and delete them, but more efficiently than in the previous example
409 (because we avoid the need to use
410 .BR fork (2)
411 and
412 .BR exec (2)
413 to launch
414 .B rm
415 and we don't need the extra
416 .B xargs
417 process).
418
419 .P
420 .nf
421 .B cut \-d: \-f1 < /etc/passwd | sort | xargs echo
422
423 .fi
424 Generates a compact listing of all the users on the system.
425 .
426 .SH "EXIT STATUS"
427 .B xargs
428 exits with the following status:
429 .RS
430 .IP 0
431 if it succeeds
432 .IP 123
433 if any invocation of the command exited with status 1\(en125
434 .IP 124
435 if the command exited with status 255
436 .IP 125
437 if the command is killed by a signal
438 .IP 126
439 if the command cannot be run
440 .IP 127
441 if the command is not found
442 .IP 1
443 if some other error occurred.
444 .RE
445
446 .P
447 Exit codes greater than 128 are used by the shell to indicate that
448 a program died due to a fatal signal.
449 .
450 .SH "STANDARDS CONFORMANCE"
451 As of GNU xargs version 4.2.9, the default behaviour of
452 .B xargs
453 is not to have a logical end-of-file marker.
454 POSIX (IEEE Std 1003.1, 2004 Edition) allows this.
455 .P
456 The \-l and \-i options appear in the 1997 version of the POSIX
457 standard, but do not appear in the 2004 version of the standard.
458 Therefore you should use \-L and \-I instead, respectively.
459 .P
460 The \-o option is an extension to the POSIX standard for better
461 compatibility with BSD.
462 .P
463 The POSIX standard allows implementations to have a limit on the size
464 of arguments to the
465 .B exec
466 functions.
467 This limit could be as low as 4096 bytes including the size of the
468 environment.
469 For scripts to be portable, they must not rely on a larger value.
470 However, I know of no implementation whose actual limit is that small.
471 The
472 .B \-\-show\-limits
473 option can be used to discover the actual limits in force on the
474 current system.
475
476 In versions of
477 .B xargs
478 up to and including version 4.9.0, SIGUSR1 and SIGUSR2 would
479 not cause
480 .B xargs
481 to terminate even if the
482 .B \-P
483 option was not used.
484 .
485 .SH "HISTORY"
486
487 The
488 .B xargs
489 program was invented by Herb Gellis at Bell Labs.
490 See the Texinfo manual for findutils,
491 .IR "Finding Files" ,
492 for more information.
493 .
494 .SH "BUGS"
495 It is not possible for
496 .B xargs
497 to be used securely, since there will always be a time gap between the
498 production of the list of input files and their use in the commands
499 that
500 .B xargs
501 issues.
502 If other users have access to the system, they can manipulate
503 the filesystem during this time window to force the action of the
504 commands
505 .B xargs
506 runs to apply to files that you didn't intend.
507 For a more detailed discussion of this and related problems, please refer
508 to the ``Security Considerations'' chapter in the findutils Texinfo
509 documentation.
510 The
511 .B \-execdir
512 option of
513 .B find
514 can often be used as a more secure alternative.
515
516 When you use the
517 .B \-I
518 option, each line read from the input is buffered internally.
519 This means that there is an upper limit on the length of input line that
520 .B xargs
521 will accept when used with the
522 .B \-I
523 option.
524 To work around this limitation,
525 you can use the
526 .B \-s
527 option to increase the amount of
528 buffer space that
529 .B xargs
530 uses, and you can also use an extra invocation of
531 .B xargs
532 to ensure that very long lines do not occur.
533 For example:
534 .P
535 .B somecommand | xargs \-s 50000 echo | xargs \-I '{}' \-s 100000 rm '{}'
536 .P
537 Here, the first invocation of
538 .B xargs
539 has no input line length limit
540 because it doesn't use the
541 .B \-i
542 option.
543 The second invocation of
544 .B xargs
545 does have such a limit,
546 but we have ensured that it never encounters
547 a line which is longer than it can handle.
548 This is not an ideal solution.
549 Instead, the
550 .B \-i
551 option should not impose a line length
552 limit,
553 which is why this discussion appears in the BUGS section.
554 The problem doesn't occur with the output of
555 .BR find (1)
556 because it emits just one filename per line.
557 .P
558 In versions of
559 .B xargs
560 up to and including version 4.9.0,
561 .B xargs -P
562 would exit while some of its children were still running, if one of
563 them exited with status 255.
564 .
565 .SH "REPORTING BUGS"
566 GNU findutils online help: <https://www.gnu.org/software/findutils/#get-help>
567 .br
568 Report any translation bugs to <https://translationproject.org/team/>
569 .PP
570 Report any other issue via the form at the GNU Savannah bug tracker:
571 .RS
572 <https://savannah.gnu.org/bugs/?group=findutils>
573 .RE
574 General topics about the GNU findutils package are discussed at the
575 .I bug\-findutils
576 mailing list:
577 .RS
578 <https://lists.gnu.org/mailman/listinfo/bug-findutils>
579 .RE
580 .
581 .SH COPYRIGHT
582 Copyright \(co 1990\(en2024 Free Software Foundation, Inc.
583 License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
584 .br
585 This is free software: you are free to change and redistribute it.
586 There is NO WARRANTY, to the extent permitted by law.
587 .
588 .SH "SEE ALSO"
589 .BR find (1),
590 .BR kill (1),
591 .BR locate (1),
592 .BR updatedb (1),
593 .BR fork (2),
594 .BR execvp (3),
595 .BR locatedb (5),
596 .BR signal (7)
597 .PP
598 Full documentation <https://www.gnu.org/software/findutils/xargs>
599 .br
600 or available locally via:
601 .B info xargs