diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/setenv.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/setenv.3p | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/setenv.3p b/man-pages-posix-2017/man3p/setenv.3p new file mode 100644 index 0000000..2a098e8 --- /dev/null +++ b/man-pages-posix-2017/man3p/setenv.3p @@ -0,0 +1,169 @@ +'\" et +.TH SETENV "3P" 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 +setenv +\(em add or change environment variable +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> +.P +int setenv(const char *\fIenvname\fP, const char *\fIenvval\fP, int \fIoverwrite\fP); +.fi +.SH DESCRIPTION +The +\fIsetenv\fR() +function shall update or add a variable in the environment of the +calling process. The +.IR envname +argument points to a string containing the name of an environment +variable to be added or altered. The environment variable shall be set +to the value to which +.IR envval +points. The function shall fail if +.IR envname +points to a string which contains an +.BR '=' +character. If the environment variable named by +.IR envname +already exists and the value of +.IR overwrite +is non-zero, the function shall return success and the environment +shall be updated. If the environment variable named by +.IR envname +already exists and the value of +.IR overwrite +is zero, the function shall return success and the environment shall +remain unchanged. +.P +The +\fIsetenv\fR() +function shall update the list of pointers to which +.IR environ +points. +.P +The strings described by +.IR envname +and +.IR envval +are copied by this function. +.P +The +\fIsetenv\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, zero shall be returned. Otherwise, \-1 +shall be returned, +.IR errno +set to indicate the error, and the environment shall be unchanged. +.SH ERRORS +The +\fIsetenv\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR envname +argument points to an empty string or points to a string containing an +.BR '=' +character. +.TP +.BR ENOMEM +Insufficient memory was available to add a variable or its value to the +environment. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +See +\fIexec\fR() +for restrictions on changing the environment in multi-threaded +applications. +.SH RATIONALE +Unanticipated results may occur if +\fIsetenv\fR() +changes the external variable +.IR environ . +In particular, if the optional +.IR envp +argument to +\fImain\fR() +is present, it is not changed, and thus may point to an obsolete copy +of the environment (as may any other copy of +.IR environ ). +However, other than the aforementioned restriction, the standard +developers intended that the traditional method of walking through +the environment by way of the +.IR environ +pointer must be supported. +.P +It was decided that +\fIsetenv\fR() +should be required by this version because it addresses a piece of +missing functionality, and does not impose a significant burden on the +implementor. +.P +There was considerable debate as to whether the System V +\fIputenv\fR() +function or the BSD +\fIsetenv\fR() +function should be required as a mandatory function. The +\fIsetenv\fR() +function was chosen because it permitted the implementation of the +\fIunsetenv\fR() +function to delete environmental variables, without specifying an +additional interface. The +\fIputenv\fR() +function is available as part of the XSI option. +.P +The standard developers considered requiring that +\fIsetenv\fR() +indicate an error when a call to it would result in exceeding +{ARG_MAX}. +The requirement was rejected since the condition might be temporary, +with the application eventually reducing the environment size. The +ultimate success or failure depends on the size at the time of a call +to +.IR exec , +which returns an indication of this error condition. +.P +See also the RATIONALE section in +.IR "\fIgetenv\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetenv\fR\^(\|)", +.IR "\fIputenv\fR\^(\|)", +.IR "\fIunsetenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<stdlib.h>\fP", +.IR "\fB<sys_types.h>\fP", +.IR "\fB<unistd.h>\fP" +.\" +.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 . |