Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 332 insertions, 0 deletions

diff --git a/upstream/archlinux/man1p/env.1p b/upstream/archlinux/man1p/env.1p
new file mode 100644
index 00000000..a7f05041
--- /dev/null
+++ b/upstream/archlinux/man1p/env.1p
@@ -0,0 +1,332 @@
+'\" et
+.TH ENV "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+env
+\(em set the environment for command invocation
+.SH SYNOPSIS
+.LP
+.nf
+env \fB[\fR-i\fB] [\fIname\fR=\fIvalue\fB]\fR... \fB[\fIutility\fB [\fIargument\fR...\fB]]\fR
+.fi
+.SH DESCRIPTION
+The
+.IR env
+utility shall obtain the current environment, modify it according to
+its arguments, then invoke the utility named by the
+.IR utility
+operand with the modified environment.
+.P
+Optional arguments shall be passed to
+.IR utility .
+.P
+If no
+.IR utility
+operand is specified, the resulting environment shall be written to the
+standard output, with one
+.IR name =\c
+.IR value
+pair per line.
+.P
+If the first argument is
+.BR '\-' ,
+the results are unspecified.
+.SH OPTIONS
+The
+.IR env
+utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
+.IR "Section 12.2" ", " "Utility Syntax Guidelines",
+except for the unspecified usage of
+.BR '\-' .
+.P
+The following options shall be supported:
+.IP "\fB\-i\fP" 10
+Invoke
+.IR utility
+with exactly the environment specified by the arguments; the inherited
+environment shall be ignored completely.
+.SH OPERANDS
+The following operands shall be supported:
+.IP "\fIname\fR=\fIvalue\fR" 10
+Arguments of the form
+.IR name =\c
+.IR value
+shall modify the execution environment, and shall be placed into the
+inherited environment before the
+.IR utility
+is invoked.
+.IP "\fIutility\fR" 10
+The name of the utility to be invoked. If the
+.IR utility
+operand names any of the special built-in utilities in
+.IR "Section 2.14" ", " "Special Built-In Utilities",
+the results are undefined.
+.IP "\fIargument\fR" 10
+A string to pass as an argument for the invoked utility.
+.SH STDIN
+Not used.
+.SH "INPUT FILES"
+None.
+.SH "ENVIRONMENT VARIABLES"
+The following environment variables shall affect the execution of
+.IR env :
+.IP "\fILANG\fP" 10
+Provide a default value for the internationalization variables that are
+unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
+.IR "Section 8.2" ", " "Internationalization Variables"
+for the precedence of internationalization variables used to determine
+the values of locale categories.)
+.IP "\fILC_ALL\fP" 10
+If set to a non-empty string value, override the values of all the
+other internationalization variables.
+.IP "\fILC_CTYPE\fP" 10
+Determine the locale for the interpretation of sequences of bytes of
+text data as characters (for example, single-byte as opposed to
+multi-byte characters in arguments).
+.IP "\fILC_MESSAGES\fP" 10
+.br
+Determine the locale that should be used to affect the format and
+contents of diagnostic messages written to standard error.
+.IP "\fINLSPATH\fP" 10
+Determine the location of message catalogs for the processing of
+.IR LC_MESSAGES .
+.IP "\fIPATH\fP" 10
+Determine the location of the
+.IR utility ,
+as described in the Base Definitions volume of POSIX.1\(hy2017,
+.IR "Chapter 8" ", " "Environment Variables".
+If
+.IR PATH
+is specified as a
+.IR name =\c
+.IR value
+operand to
+.IR env ,
+the
+.IR value
+given shall be used in the search for
+.IR utility .
+.SH "ASYNCHRONOUS EVENTS"
+Default.
+.SH STDOUT
+If no
+.IR utility
+operand is specified, each
+.IR name =\c
+.IR value
+pair in the resulting environment shall be written in the form:
+.sp
+.RS 4
+.nf
+
+"%s=%s\en", <\fIname\fR>, <\fIvalue\fR>
+.fi
+.P
+.RE
+.P
+If the
+.IR utility
+operand is specified, the
+.IR env
+utility shall not write to standard output.
+.SH STDERR
+The standard error shall be used only for diagnostic messages.
+.SH "OUTPUT FILES"
+None.
+.SH "EXTENDED DESCRIPTION"
+None.
+.SH "EXIT STATUS"
+If
+.IR utility
+is invoked, the exit status of
+.IR env
+shall be the exit status of
+.IR utility ;
+otherwise, the
+.IR env
+utility shall exit with one of the following values:
+.IP "\0\0\0\00" 8
+The
+.IR env
+utility completed successfully.
+.IP "1\-125" 8
+An error occurred in the
+.IR env
+utility.
+.IP "\0\0126" 8
+The utility specified by
+.IR utility
+was found but could not be invoked.
+.IP "\0\0127" 8
+The utility specified by
+.IR utility
+could not be found.
+.SH "CONSEQUENCES OF ERRORS"
+Default.
+.LP
+.IR "The following sections are informative."
+.SH "APPLICATION USAGE"
+The
+.IR command ,
+.IR env ,
+.IR nice ,
+.IR nohup ,
+.IR time ,
+and
+.IR xargs
+utilities have been specified to use exit code 127 if an error occurs
+so that applications can distinguish ``failure to find a utility'' from
+``invoked utility exited with an error indication''. The value 127 was
+chosen because it is not commonly used for other meanings; most
+utilities use small values for ``normal error conditions'' and the
+values above 128 can be confused with termination due to receipt of a
+signal. The value 126 was chosen in a similar manner to indicate that
+the utility could be found, but not invoked. Some scripts produce
+meaningful error messages differentiating the 126 and 127 cases. The
+distinction between exit codes 126 and 127 is based on KornShell
+practice that uses 127 when all attempts to
+.IR exec
+the utility fail with
+.BR [ENOENT] ,
+and uses 126 when any attempt to
+.IR exec
+the utility fails for any other reason.
+.P
+Historical implementations of the
+.IR env
+utility use the
+\fIexecvp\fR()
+or
+\fIexeclp\fR()
+functions defined in the System Interfaces volume of POSIX.1\(hy2017 to invoke the specified utility; this
+provides better performance and keeps users from having to escape
+characters with special meaning to the shell. Therefore, shell
+functions, special built-ins, and built-ins that are only provided by
+the shell are not found.
+.SH EXAMPLES
+The following command:
+.sp
+.RS 4
+.nf
+
+env -i PATH=/mybin:"$PATH" $(getconf V7_ENV) mygrep xyz myfile
+.fi
+.P
+.RE
+.P
+invokes the command
+.IR mygrep
+with a new
+.IR PATH
+value as the only entry in its environment other than any variables
+required by the implementation for conformance. In this case,
+.IR PATH
+is used to locate
+.IR mygrep ,
+which is expected to reside in
+.BR /mybin .
+.SH RATIONALE
+As with all other utilities that invoke other utilities, this volume of POSIX.1\(hy2017 only
+specifies what
+.IR env
+does with standard input, standard output, standard error, input files,
+and output files. If a utility is executed, it is not constrained by
+the specification of input and output by
+.IR env .
+.P
+The
+.BR \-i
+option was added to allow the functionality of the removed
+.BR \-
+option in a manner compatible with the Utility Syntax Guidelines. It
+is possible to create a non-conforming environment using the
+.BR \-i
+option, as it may remove environment variables required by the
+implementation for conformance. The following will preserve these
+environment variables as well as preserve the
+.IR PATH
+for conforming utilities:
+.sp
+.RS 4
+.nf
+
+IFS=\(aq
+\&\(aq
+# The preceding value should be <space><tab><newline>.
+# Set IFS to its default value.
+.P
+set -f
+# disable pathname expansion
+.P
+\eunalias -a
+# Unset all possible aliases.
+# Note that unalias is escaped to prevent an alias
+# being used for unalias.
+# This step is not strictly necessary, since aliases are not inherited,
+# and the ENV environment variable is only used by interactive shells,
+# the only way any aliases can exist in a script is if it defines them
+# itself.
+.P
+unset -f env getconf
+# Ensure env and getconf are not user functions.
+.P
+env -i $(getconf V7_ENV) PATH="$(getconf PATH)" command
+.fi
+.P
+.RE
+.P
+Some have suggested that
+.IR env
+is redundant since the same effect is achieved by:
+.sp
+.RS 4
+.nf
+
+name=value ... utility \fB[\fR argument ... \fB]\fR
+.fi
+.P
+.RE
+.P
+The example is equivalent to
+.IR env
+when an environment variable is being added to the environment of the
+command, but not when the environment is being set to the given value.
+The
+.IR env
+utility also writes out the current environment if invoked without
+arguments. There is sufficient functionality beyond what the example
+provides to justify inclusion of
+.IR env .
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "Section 2.14" ", " "Special Built-In Utilities",
+.IR "Section 2.5" ", " "Parameters and Variables"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "Chapter 8" ", " "Environment Variables",
+.IR "Section 12.2" ", " "Utility Syntax Guidelines"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group.
+In the event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .