diff options
Diffstat (limited to 'upstream/debian-bookworm/man1/xargs.1')
| -rw-r--r-- | upstream/debian-bookworm/man1/xargs.1 | 511 |
1 files changed, 511 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man1/xargs.1 b/upstream/debian-bookworm/man1/xargs.1 new file mode 100644 index 00000000..f743e60c --- /dev/null +++ b/upstream/debian-bookworm/man1/xargs.1 @@ -0,0 +1,511 @@ +.TH XARGS 1 \" -*- nroff -*- +.SH NAME +xargs \- build and execute command lines from standard input +.SH SYNOPSIS +.B xargs +.nh +[\fIoptions\fR] +[\fIcommand\fR [\fIinitial-arguments\fR]] +.hy +. +.SH DESCRIPTION +This manual page +documents the GNU version of +.BR xargs . +.B xargs +reads items from the standard input, delimited by blanks (which can be +protected with double or single quotes or a backslash) or newlines, +and executes the +.I command +(default is +.IR echo ) +one or more times with any +.I initial-arguments +followed by items read from standard input. Blank lines on the +standard input are ignored. +.P +The command line for +.I command +is built up until it reaches a system-defined limit (unless the +.B \-n +and +.B \-L +options are used). The specified +.I command +will be invoked as many times as necessary to use up the list of input +items. In general, there will be many fewer invocations of +.I command +than there were items in the input. This will normally have +significant performance benefits. Some commands can usefully be +executed in parallel too; see the +.B \-P +option. +.P +Because Unix filenames can contain blanks and newlines, this default +behaviour is often problematic; filenames containing blanks +and/or newlines are incorrectly processed by +.BR xargs . +In these situations it is better to use the +.B \-0 +option, which +prevents such problems. When using this option you will need to +ensure that the program which produces the input for +.B xargs +also uses a null character as a separator. If that program is +GNU +.B find +for example, the +.B \-print0 +option does this for you. +.P +If any invocation of the command exits with a status of 255, +.B xargs +will stop immediately without reading any further input. An error +message is issued on stderr when this happens. +. +.SH OPTIONS +.TP +.B \-0, \-\-null +Input items are terminated by a null character instead of by +whitespace, and the quotes and backslash are not special (every +character is taken literally). Disables the end of file string, which +is treated like any other argument. Useful when input items might +contain white space, quote marks, or backslashes. The GNU find +\-print0 option produces input suitable for this mode. + +.TP +.BI "\-a " file ", \-\-arg\-file=" file +Read items from +.I file +instead of standard input. If you use this option, stdin remains +unchanged when commands are run. Otherwise, stdin is redirected +from +.IR /dev/null . + +.TP +.BI "\-\-delimiter=" delim ", \-d" " delim" +Input items are terminated by the specified character. The specified +delimiter may be a single character, a C-style character escape such +as +.BR \en , +or an octal or hexadecimal escape code. Octal and hexadecimal +escape codes are understood as for the +.B printf +command. Multibyte characters are not supported. +When processing the input, quotes and backslash are not special; every +character in the input is taken literally. The +.B \-d +option disables any end-of-file string, which is treated like any +other argument. You can use this option when the input consists of +simply newline-separated items, although it is almost always better to +design your program to use +.B \-\-null +where this is possible. + +.TP +.BI \-E " eof-str" +Set the end of file string to \fIeof-str\fR. If the end of file +string occurs as a line of input, the rest of the input is ignored. +If neither +.B \-E +nor +.B \-e +is used, no end of file string is used. +.TP +.BR \-e "[\fIeof-str\fR], " "\-\-eof" [\fI=eof-str\fR] +This option is a synonym for the +.B \-E +option. Use +.B \-E +instead, +because it is POSIX compliant while this option is not. If +\fIeof-str\fR is omitted, there is no end of file string. If neither +.B \-E +nor +.B \-e +is used, no end of file string is used. +.TP +.BI \-I " replace-str" +Replace occurrences of \fIreplace-str\fR in the initial-arguments with +names read from standard input. Also, unquoted blanks do not +terminate input items; instead the separator is the newline character. +Implies +.B \-x +and +.B \-L +1. +.TP +.BR \-i "[\fIreplace-str\fR], " "\-\-replace" [\fI=replace-str\fR] +This option is a synonym for +.BI \-I replace-str +if +.I replace-str +is specified. If the +.I replace-str +argument is missing, the effect is the same as +.BR \-I {}. +This option is deprecated; use +.B \-I +instead. +.TP +.BI \-L " max-lines" +Use at most \fImax-lines\fR nonblank input lines per command line. +Trailing blanks cause an input line to be logically continued on the +next input line. Implies +.BR \-x . +.TP +.BR \-l "[\fImax-lines\fR], " \-\-max-lines "[=\fImax-lines\fR]" +Synonym for the +.B \-L +option. Unlike +.BR \-L , +the +.I max-lines +argument is optional. If +.I max-lines +is not specified, it defaults to one. The +.B \-l +option is deprecated since the POSIX standard specifies +.B \-L +instead. +.TP +.BI \-n " max-args\fB, \fI" "\-\-max\-args" \fR=\fImax-args +Use at most \fImax-args\fR arguments per command line. Fewer than +.I max-args +arguments will be used if the size (see the +.B \-s +option) is exceeded, unless the +.B \-x +option is given, in which case +.B xargs will exit. +.TP +.BI \-P " max-procs\fR, \fI" \-\-max\-procs "\fR=\fImax-procs" +Run up to +.I max-procs +processes at a time; the default is 1. If +.I max-procs +is 0, +.B xargs +will run as many processes as +possible at a time. Use the +.B \-n +option or the +.B \-L +option with +.BR \-P ; +otherwise chances are that only one exec will be done. +While +.B xargs +is running, you can send its process a SIGUSR1 signal to increase the +number of commands to run simultaneously, or a SIGUSR2 to decrease the +number. You cannot increase it above an implementation-defined limit +(which is shown with \-\-show-limits). You cannot decrease it below +1. +.B xargs +never terminates its commands; when asked to decrease, it merely +waits for more than one existing command to terminate before starting +another. + +.B Please note +that it is up to the called processes to properly manage parallel +access to shared resources. For example, if more than one of them +tries to print to stdout, the output will be produced in an +indeterminate order (and very likely mixed up) unless the processes +collaborate in some way to prevent this. Using some kind of locking +scheme is one way to prevent such problems. In general, using a +locking scheme will help ensure correct output but reduce performance. +If you don't want to tolerate the performance difference, simply +arrange for each process to produce a separate output file (or +otherwise use separate resources). +.TP +.B \-o, \-\-open\-tty +Reopen stdin as +.I /dev/tty +in the child process before executing the command. This is useful if +you want +.B xargs +to run an interactive application. +.TP +.B \-p, \-\-interactive +Prompt the user about whether to run each command line and read a line +from the terminal. Only run the command line if the response starts +with `y' or `Y'. Implies +.BR -t . +.TP +.BR \-\-process\-slot\-var "=\fIname\fR" +Set the environment variable +.I name +to a unique value in each running child process. Values are reused +once child processes exit. This can be used in a rudimentary load +distribution scheme, for example. +.TP +.B \-r, \-\-no\-run\-if\-empty +If the standard input does not contain any nonblanks, do not run the +command. Normally, the command is run once even if there is no input. +This option is a GNU extension. +.TP +.BI -s " max-chars\fR, \fI" \-\-max\-chars "=\fImax-chars\fR" +Use at most \fImax-chars\fR characters per command line, including the +command and initial-arguments and the terminating nulls at the ends of +the argument strings. The largest allowed value is system-dependent, +and is calculated as the argument length limit for exec, less the size +of your environment, less 2048 bytes of headroom. If this value is +more than 128KiB, 128Kib is used as the default value; otherwise, the +default value is the maximum. 1KiB is 1024 bytes. +.B xargs +automatically adapts to tighter constraints. +.TP +.B "\-\-show\\-limits" +Display the limits on the command-line length which are imposed by the +operating system, +.BR xargs ' +choice of buffer size and the +.B \-s +option. Pipe the input from +.I /dev/null +(and perhaps specify +.BR --no-run-if-empty ) +if you don't want +.B xargs +to do anything. +.TP +.B \-t, \-\-verbose +Print the command line on the standard error output before executing +it. +.TP +.B \-x, \-\-exit +Exit if the size (see the +.B \-s +option) is exceeded. +.TP +.B "\-\-help" +Print a summary of the options to +.B xargs +and exit. +.TP +.B "\-\-version" +Print the version number of +.B xargs +and exit. +.PP +The options +.B \-\-max-lines +(\fB\-L\fP, \fB\-l\fP), +.B \-\-replace +(\fB\-I\fP, \fB\-i\fP) +and +.B \-\-max-args +(\fB\-n\fP) +are mutually exclusive. If some of them are specified at the same +time, then +.B xargs +will generally use the option specified last on the command line, +i.e., it will reset the value of the offending option (given before) +to its default value. +Additionally, +.B xargs +will issue a warning diagnostic on +.IR stderr . +The exception to this rule is that the special +.I max-args +value +.I 1 +('\fB\-n\fP\fI1\fP') +is ignored after the +.B \-\-replace +option and its aliases +.B \-I +and +.BR \-i , +because it would not actually conflict. + +. +.SH "EXAMPLES" +.nf +.B find /tmp \-name core \-type f \-print | xargs /bin/rm \-f + +.fi +Find files named +.B core +in or below the directory +.B /tmp +and delete them. Note that this will work incorrectly if there are +any filenames containing newlines or spaces. +.P +.B find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f + +Find files named +.B core +in or below the directory +.B /tmp +and delete them, processing filenames in such a way that file or +directory names containing spaces or newlines are correctly handled. + +.P +.B find /tmp \-depth \-name core \-type f \-delete + +Find files named +.B core +in or below the directory +.B /tmp +and delete them, but more efficiently than in the previous example +(because we avoid the need to use +.BR fork (2) +and +.BR exec (2) +to launch +.B rm +and we don't need the extra +.B xargs +process). + +.P +.nf +.B cut \-d: \-f1 < /etc/passwd | sort | xargs echo + +.fi +Generates a compact listing of all the users on the system. +. +.SH "EXIT STATUS" +.B xargs +exits with the following status: +.RS +.IP 0 +if it succeeds +.IP 123 +if any invocation of the command exited with status 1-125 +.IP 124 +if the command exited with status 255 +.IP 125 +if the command is killed by a signal +.IP 126 +if the command cannot be run +.IP 127 +if the command is not found +.IP 1 +if some other error occurred. +.RE + +.P +Exit codes greater than 128 are used by the shell to indicate that +a program died due to a fatal signal. +. +.SH "STANDARDS CONFORMANCE" +As of GNU xargs version 4.2.9, the default behaviour of +.B xargs +is not to have a logical end-of-file marker. POSIX (IEEE Std 1003.1, +2004 Edition) allows this. +.P +The \-l and \-i options appear in the 1997 version of the POSIX +standard, but do not appear in the 2004 version of the standard. +Therefore you should use \-L and \-I instead, respectively. +.P +The \-o option is an extension to the POSIX standard for better +compatibility with BSD. +.P +The POSIX standard allows implementations to have a limit on the size +of arguments to the +.B exec +functions. This limit could be as low as 4096 bytes including the size of the +environment. For scripts to be portable, they must not rely on a +larger value. However, I know of no implementation whose actual limit +is that small. The +.B \-\-show\-limits +option can be used to discover the actual limits in force on the +current system. +. +.SH "BUGS" +It is not possible for +.B xargs +to be used securely, since there will always be a time gap between the +production of the list of input files and their use in the commands +that +.B xargs +issues. If other users have access to the system, they can manipulate +the filesystem during this time window to force the action of the +commands +.B xargs +runs to apply to files that you didn't intend. For a more detailed +discussion of this and related problems, please refer to the +``Security Considerations'' chapter in the findutils Texinfo +documentation. The +.B \-execdir +option of +.B find +can often be used as a more secure alternative. + +When you use the +.B \-I +option, each line read from the input is buffered +internally. This means that there is an upper limit on the length +of input line that +.B xargs +will accept when used with the +.B \-I +option. To work around this +limitation, you can use the +.B \-s +option to increase the amount of +buffer space that +.B xargs +uses, and you can also use an extra invocation of +.B xargs +to ensure that very long lines do not occur. +For example: +.P +.B somecommand | xargs \-s 50000 echo | xargs \-I '{}' \-s 100000 rm '{}' +.P +Here, the first invocation of +.B xargs +has no input line length limit +because it doesn't use the +.B \-i +option. The second invocation of +.B xargs +does have such a limit, but we have ensured that it never encounters +a line which is longer than it can handle. This is not an ideal +solution. Instead, the +.B \-i +option should not impose a line length +limit, which is why this discussion appears in the BUGS section. +The problem doesn't occur with the output of +.BR find (1) +because it emits just one filename per line. +. +.SH "REPORTING BUGS" +GNU findutils online help: <https://www.gnu.org/software/findutils/#get-help> +.br +Report any translation bugs to <https://translationproject.org/team/> +.PP +Report any other issue via the form at the GNU Savannah bug tracker: +.RS +<https://savannah.gnu.org/bugs/?group=findutils> +.RE +General topics about the GNU findutils package are discussed at the +.I bug\-findutils +mailing list: +.RS +<https://lists.gnu.org/mailman/listinfo/bug-findutils> +.RE +. +.SH COPYRIGHT +Copyright \(co 1990-2022 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. +.br +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +. +.SH "SEE ALSO" +.BR find (1), +.BR kill (1), +.BR locate (1), +.BR updatedb (1), +.BR fork (2), +.BR execvp (3), +.BR locatedb (5), +.BR signal (7) +.PP +Full documentation <https://www.gnu.org/software/findutils/xargs> +.br +or available locally via: +.B info xargs |