huschi.net

SETENV(3P)                 POSIX Programmer's Manual                SETENV(3P)
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.
NAME
       setenv -- add or change environment variable
SYNOPSIS
       #include <stdlib.h>
       int setenv(const char *envname, const char *envval, int overwrite);
DESCRIPTION
       The setenv() function shall update or add a variable in the environment
       of  the  calling  process. The envname argument points to a string con-
       taining the name of an environment variable to be added or altered. The
       environment  variable shall be set to the value to which envval points.
       The function shall fail if envname points to a string which contains an
       '='  character.  If  the  environment variable named by envname already
       exists and the value of  overwrite  is  non-zero,  the  function  shall
       return success and the environment shall be updated. If the environment
       variable named by envname already exists and the value of overwrite  is
       zero,  the  function  shall  return  success  and the environment shall
       remain unchanged.
       The setenv() function shall update the list of pointers to which  envi-
       ron points.
       The  strings  described  by envname and envval are copied by this func-
       tion.
       The setenv() function need not be thread-safe.
RETURN VALUE
       Upon successful completion, zero shall be returned. Otherwise, -1 shall
       be returned, errno set to indicate the error, and the environment shall
       be unchanged.
ERRORS
       The setenv() function shall fail if:
       EINVAL The envname argument points to an empty string or  points  to  a
              string containing an '=' character.
       ENOMEM Insufficient memory was available to add a variable or its value
              to the environment.
       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       See exec() for restrictions  on  changing  the  environment  in  multi-
       threaded applications.
RATIONALE
       Unanticipated  results may occur if setenv() changes the external vari-
       able environ.  In particular, if the optional envp argument  to  main()
       is  present,  it is not changed, and thus may point to an obsolete copy
       of the environment (as may any other copy of environ).  However,  other
       than  the  aforementioned restriction, the standard developers intended
       that the traditional method of walking through the environment  by  way
       of the environ pointer must be supported.
       It was decided that setenv() should be required by this version because
       it addresses a piece of missing functionality, and does  not  impose  a
       significant burden on the implementor.
       There was considerable debate as to whether the System V putenv() func-
       tion or the BSD setenv() function should be  required  as  a  mandatory
       function.  The  setenv()  function  was chosen because it permitted the
       implementation of the unsetenv() function to delete environmental vari-
       ables,  without  specifying an additional interface. The putenv() func-
       tion is available as part of the XSI option.
       The standard developers considered requiring that setenv() 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  exec,
       which returns an indication of this error condition.
       See also the RATIONALE section in getenv().
FUTURE DIRECTIONS
       None.
SEE ALSO
       exec, getenv(), putenv(), unsetenv()
       The Base Definitions volume of POSIX.1-2008, <stdlib.h>, <sys_types.h>,
       <unistd.h>
COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri-
       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) 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.unix.org/online.html .
       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.ker-
       nel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group                  2013                           SETENV(3P)