Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
GETENV(3)		     Library Functions Manual		       GETENV(3)

NAME
     clearenv,	getenv, getenv_r, putenv, secure_getenv, setenv, unsetenv -- en-
     vironment variable functions

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <stdlib.h>

     int
     clearenv(void);

     char *
     getenv(const char *name);

     int
     getenv_r(const char *name, char *buf, size_t len);

     char *
     secure_getenv(const char *name);

     int
     setenv(const char *name, const char *value, int overwrite);

     int
     putenv(char *string);

     int
     unsetenv(const char *name);

DESCRIPTION
     These functions set, unset and fetch environment variables  from  the  host
     environment list.

     The  clearenv()  function	clears all environment variables.  New variables
     can be added using setenv() and putenv().

     The getenv() function obtains the current value of the environment variable
     designated by name.  The application should not modify the  string  pointed
     to by the getenv() function.

     The  getenv_r() function obtains the current value of the environment vari-
     able designated by name and copies it into the buffer buf of length len.

     The secure_getenv() returns NULL when the environment  cannot  be	trusted,
     otherwise	it acts like getenv().	The environment currently is not trusted
     when issetugid(2) returns a non-zero value, but  other  conditions  may  be
     added in the future.

     The  setenv()  function  inserts or resets the environment variable name in
     the current environment list.  If the variable name does not exist  in  the
     list, it is inserted with the given value.  If the variable does exist, the
     argument overwrite is tested; if overwrite is zero, the variable is not re-
     set, otherwise it is reset to the given value.

     The putenv() function takes an argument of the form ``name=value'' and puts
     it  directly  into  the current environment, so altering the argument shall
     change the environment.  If the variable name does not exist in  the  list,
     it  is  inserted with the given value.  If the variable name does exist, it
     is reset to the given value.

     The unsetenv() function deletes all instances of the variable name  pointed
     to by name from the list.

     If  corruption  (e.g.,  a	name without a value) is detected while making a
     copy of environ for internal usage, then setenv(), unsetenv() and	putenv()
     will output a warning to stderr about the issue, drop the corrupt entry and
     complete the task without error.

RETURN VALUES
     The  getenv()  function  returns the value of the environment variable as a
     NUL-terminated string.  If the variable name is not in the current environ-
     ment, NULL is returned.

     The secure_getenv() function returns NULL if the process is in "secure exe-
     cution," otherwise it will call getenv().

     The clearenv(), getenv_r(), setenv(), putenv(),  and  unsetenv()  functions
     return  the  value  0 if successful; otherwise the value -1 is returned and
     the global variable errno is set to indicate the error.

ERRORS
     [EINVAL]		The  function  getenv(),  getenv_r(),  setenv()  or  un-
			setenv()  failed  because  the	name  is a NULL pointer,
			points to an empty string, or points to  a  string  con-
			taining an "=" character.

			The  function  putenv()  failed because string is a NULL
			pointer, string is without an "=" character  or  "="  is
			the first character in string.	This does not follow the
			POSIX specification.

     [ENOENT]		The  function  getenv_r()  failed  because the requested
			variable was not found in the environment.

     [ENOMEM]		The function setenv(), unsetenv() or putenv() failed be-
			cause they were unable to allocate memory for the  envi-
			ronment.

     [ERANGE]		The  function getenv_r() failed because the value of the
			requested variable was too long to fit in  the	provided
			buffer.

SEE ALSO
     csh(1), sh(1), execve(2), environ(7)

STANDARDS
     The  getenv()  function  conforms	to  ISO/IEC  9899:1990 ("ISO C90").  The
     setenv(),	putenv()  and  unsetenv()  functions  conforms	 to   IEEE   Std
     1003.1-2001 ("POSIX.1").  The secure_getenv() function conforms to IEEE Std
     1003.1-2024 ("POSIX.1").

HISTORY
     The functions setenv() and unsetenv() appeared in Version 7 AT&T UNIX.  The
     putenv() function appeared in 4.3BSD-Reno.

     Until  FreeBSD 7.0, putenv() would make a copy of string and insert it into
     the environment using setenv().  This was changed to use string as the mem-
     ory location of the ``name=value'' pair to follow the POSIX specification.

     The clearenv() and secure_getenv() functions were added in FreeBSD 14.

     The getenv_r() function first appeared in	NetBSD	4.0  and  was  added  in
     FreeBSD 15.

BUGS
     Successive calls to setenv() that assign a larger-sized value than any pre-
     vious value to the same name will result in a memory leak.  The FreeBSD se-
     mantics  for  this  function (namely, that the contents of value are copied
     and that old values remain accessible indefinitely) make this bug	unavoid-
     able.   Future versions may eliminate one or both of these semantic guaran-
     tees in order to fix the bug.

FreeBSD ports 15.1		 April 22, 2025 		       GETENV(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=getenv&sektion=3&manpath=FreeBSD+15.1-RELEASE+and+Ports>

home | help