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

FreeBSD Manual Pages

  
 
  

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

NAME
     getenv, putenv, setenv, unsetenv -- environment variable functions

SYNOPSIS
     #include <stdlib.h>

     char *
     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 getenv() function obtains the current value of	the environment	vari-
     able name.	 If the	variable name is not in	the current environment, a
     null pointer is returned.

     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 reset,	otherwise it is	reset to the given value.

     The putenv() function takes an argument of	the form name=value.  The mem-
     ory pointed to by string becomes part of the environment and must not be
     deallocated by the	caller.	 If the	variable already exists, it will be
     overwritten.  A common source of bugs is to pass a	string argument	that
     is	a locally scoped string	buffer.	 This will result in corruption	of the
     environment after leaving the scope in which the variable is defined.
     For this reason, the setenv() function is preferred over putenv().

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

RETURN VALUES
     The putenv(), setenv(), 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.

     The getenv() function returns a pointer to	the requested value, or	NULL
     if	it could not be	found.	If getenv() is successful, the string returned
     should be considered read-only.

ERRORS
     [EINVAL]		The setenv() or	unsetenv() function was	passed an
			empty name or a	NULL pointer, or was passed a name
			containing an `=' character.

			The putenv() function was passed a string that did not
			contain	an `=' character.

     [ENOMEM]		The setenv() or	putenv() function failed because it
			was unable to allocate memory for the environment.

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

STANDARDS
     The getenv() function conforms to ANSI X3.159-1989	("ANSI C89").  The
     putenv(), setenv(), and unsetenv()	functions conform to IEEE Std
     1003.1-2008 ("POSIX.1").

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

CAVEATS
     Library code must be careful about	using getenv() to read untrusted envi-
     ronment variables in setuid programs.  The	issetugid() function is	pro-
     vided for this purpose.

BSD				 July 11, 2014				   BSD

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getenv&sektion=3&manpath=OpenBSD+6.5>

home | help