diff options
Diffstat (limited to 'man-pages-posix-2003/man3p/setenv.3p')
| -rw-r--r-- | man-pages-posix-2003/man3p/setenv.3p | 125 |
1 files changed, 125 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man3p/setenv.3p b/man-pages-posix-2003/man3p/setenv.3p new file mode 100644 index 0000000..63a0cc1 --- /dev/null +++ b/man-pages-posix-2003/man3p/setenv.3p @@ -0,0 +1,125 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "SETENV" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" setenv +.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 \- add or change environment variable +.SH SYNOPSIS +.LP +\fB#include <stdlib.h> +.br +.sp +int setenv(const char *\fP\fIenvname\fP\fB, const char *\fP\fIenvval\fP\fB, +int\fP \fIoverwrite\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIsetenv\fP() function shall update or add a variable in the +environment of the calling process. The \fIenvname\fP +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 \fIenvval\fP points. The function shall +fail if \fIenvname\fP points to a string which contains an +\fB'='\fP character. If the environment variable named by \fIenvname\fP +already exists and the value of \fIoverwrite\fP is +non-zero, the function shall return success and the environment shall +be updated. If the environment variable named by +\fIenvname\fP already exists and the value of \fIoverwrite\fP is zero, +the function shall return success and the environment +shall remain unchanged. +.LP +If the application modifies \fIenviron\fP or the pointers to which +it points, the behavior of \fIsetenv\fP() is undefined. The +\fIsetenv\fP() function shall update the list of pointers to which +\fIenviron\fP points. +.LP +The strings described by \fIenvname\fP and \fIenvval\fP are copied +by this function. +.LP +The \fIsetenv\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +Upon successful completion, zero shall be returned. Otherwise, -1 +shall be returned, \fIerrno\fP set to indicate the error, and +the environment shall be unchanged. +.SH ERRORS +.LP +The \fIsetenv\fP() function shall fail if: +.TP 7 +.B EINVAL +The \fIname\fP argument is a null pointer, points to an empty string, +or points to a string containing an \fB'='\fP +character. +.TP 7 +.B ENOMEM +Insufficient memory was available to add a variable or its value to +the environment. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +See \fIexec\fP(), for restrictions on changing the environment in +multi-threaded applications. +.SH RATIONALE +.LP +Unanticipated results may occur if \fIsetenv\fP() changes the external +variable \fIenviron\fP. In particular, if the optional +\fIenvp\fP argument to \fImain\fP() is present, it is not changed, +and thus may point to an obsolete copy of the environment (as +may any other copy of \fIenviron\fP). However, other than the aforementioned +restriction, the developers of +IEEE\ Std\ 1003.1-2001 intended that the traditional method of walking +through the environment by way of the \fIenviron\fP +pointer must be supported. +.LP +It was decided that \fIsetenv\fP() should be required by this revision +because it addresses a piece of missing functionality, +and does not impose a significant burden on the implementor. +.LP +There was considerable debate as to whether the System V \fIputenv\fP() +function or the +BSD \fIsetenv\fP() function should be required as a mandatory function. +The \fIsetenv\fP() function was chosen because it +permitted the implementation of the \fIunsetenv\fP() function to delete +environmental +variables, without specifying an additional interface. The \fIputenv\fP() +function is +available as an XSI extension. +.LP +The standard developers considered requiring that \fIsetenv\fP() 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 \fIexec\fP, which returns an indication of +this error condition. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP(), \fIgetenv\fP(), \fIunsetenv\fP(), the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI<stdlib.h>\fP, \fI<sys/types.h>\fP, +\fI<unistd.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 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 . |