Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 511 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/xargs.1 b/upstream/mageia-cauldron/man1/xargs.1
new file mode 100644
index 00000000..f743e60c
--- /dev/null
+++ b/upstream/mageia-cauldron/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