usr/src/lib/libc/stdlib/getenv.3

.\" Copyright (c) 1988, 1991, 1993
.\"     The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the American National Standards Committee X3, on Information
.\" Processing Systems.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)getenv.3    8.2 (Berkeley) %G%
.\"
.Dd
.Dt GETENV 3
.Os
.Sh NAME
.Nm getenv ,
.Nm putenv ,
.Nm setenv ,
.Nm unsetenv
.Nd environment variable functions
.Sh SYNOPSIS
.Fd #include <stdlib.h>
.Ft char *
.Fn getenv "const char *name"
.Ft int
.Fn setenv "const char *name" "const char *value" "int overwrite"
.Ft int
.Fn putenv "const char *string"
.Ft void
.Fn unsetenv "const char *name"
.Sh DESCRIPTION
These functions set, unset and fetch environment variables from the
host
.Em environment list .
For compatibility with differing environment conventions,
the given arguments
.Ar name
and
.Ar value
may be appended and prepended,
respectively,
with an equal sign
.Dq Li \&= .
.Pp
The
.Fn getenv
function obtains the current value of the environment variable,
.Ar name .
If the variable
.Ar name
is not in the current environment,
a null pointer is returned.
.Pp
The
.Fn setenv
function inserts or resets the environment variable
.Ar name
in the current environment list.
If the variable
.Ar name
does not exist in the list,
it is inserted with the given
.Ar value.
If the variable does exist, the argument
.Ar overwrite
is tested; if
.Ar overwrite is
zero, the
variable is not reset, otherwise it is reset
to the given
.Ar value .
.Pp
The
.Fn putenv
function takes an argument of the form ``name=value'' and is
equivalent to:
.Bd -literal -offset indent
setenv(name, value, 1);
.Ed
.Pp
The
.Fn unsetenv
function
deletes all instances of the variable name pointed to by
.Fa name
from the list.
.Sh RETURN VALUES
The functions
.Fn setenv
and
.Fn putenv
return zero if successful; otherwise the global variable
.Va errno
is set to indicate the error and a
\-1 is returned.
.Sh ERRORS
.Bl -tag -width [ENOMEM]
.It Bq Er ENOMEM
The function
.Fn setenv
or
.Fn putenv
failed because they were unable to allocate memory for the environment.
.El
.Sh SEE ALSO
.Xr csh 1 ,
.Xr sh 1 ,
.Xr execve 2 ,
.Xr environ 7
.Sh STANDARDS
The
.Fn getenv
function conforms to
.St -ansiC .
.Sh HISTORY
The functions
.Fn setenv
and
.Fn unsetenv
appeared in
.At v7 .
The
.Fn putenv
function appeared in
.Bx 4.3 Reno .