diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/env.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/env.1p | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/env.1p b/man-pages-posix-2017/man1p/env.1p new file mode 100644 index 0000000..a7f0504 --- /dev/null +++ b/man-pages-posix-2017/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 . |