gno/usr.man/man3/getenv.3

.\" Portions of this code (where listed) are:
.\"
.\" Copyright (c) 1988, 1991 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.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"		This product includes software developed by the University of
.\"		California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     from: @(#)getenv.3	6.11 (Berkeley) 6/29/91
.\"	getenv.3,v 1.2 1993/08/01 07:44:27 mycroft Exp
.\"
.\" This man page was modified to conform with the lenviron v1.1.3
.\" release for GNO v2.0.3 by Devin Reade <gdr@myrias.com>.  lenviron
.\" was superceeded by libc as of GNO v2.0.6.
.\"
.TH GETENV 3 "29 January 1997" GNO "Library Functions"
.SH NAME
.LP
.BR getenv ,
.BR putenv ,
.BR setenv ,
.BR unsetenv ,
.BR environInit ,
.BR environPop ,
.BR environPush ,
\- environment variable functions
.SH SYNOPSIS
#include <stdlib.h>
.sp 1
char *\fBgetenv\fR (const char *\fIname\fR);
.br
int \fBputenv\fR (const char *\fIstring\fR);
.br
int \fBsetenv\fR (const char *\fIname\fR, const char *\fIvalue\fR
int \fIoverwrite\fR);
.br
void \fBunsetenv\fR (const char *\fIname\fR);
.sp 1
int \fBenvironInit\fR (void);
.br
int \fBenvironPush\fR (void);
.br
void \fBenvironPop\fR (void);
.SH DESCRIPTION
These functions set, unset and fetch environment variables from the host
.IR "environment list" .
For compatibility with differing environment conventions, the given arguments
.I name
and
.I value
may be appended and prepended, respectively, with an equal sign.
.LP
The
.B getenv
function obtains the current value of the environment variable,
.IR name .
If the variable
.I name
is not in the current environment, a null pointer is returned.
.LP
The
.B setenv
function inserts or resets the environment variable
.I name
in the current environment list.  If the variable
.I name
does not exist in the list, it is inserted with the given
.I value.
If the variable does exist, the argument
.I overwrite
is tested; if
.I overwrite
is zero, the variable is not reset, otherwise it is reset to the given
.I value.
.LP
The
.B putenv
function performs the equivalent of:
.nf

	setenv(\fIname\fR, \fIvalue\fR, 1);

.fi
and expects 
.I string
to be of the form
.IR name=value .
.LP
The
.B unsetenv
function deletes all instances of the variable name pointed to by
.I name
from the list.
.LP
The 
.BR environInit ,
.BR environPush ,
and
.BR environPop
functions are non\-standard (GNO-specific).
.LP
The
.B environInit
function is used to initialize the
.B environ
variable, since this functionality is provided by neither shell.  It
is necessary to use
.B environInit
before any explicit references to \fIenviron\fR, but if \fIenviron\fR is
not to be referenced, it is not necessary to call
.B environInit
at all.
.LP
.B environPush
and
.B environPop
are used to push and pop, respectively, the environment stack.  See
.B environ
(8) for more information.
.SH RETURN VALUES
The functions 
.BR environInit ,
.BR environPush , 
.BR putenv ,
and 
.BR setenv
return zero if successful; otherwise the global variable
.B errno
is set to indicate the error and a \-1 is returned.
.SH ERRORS
.IP \fBENOMEM\fR
The functions
.BR environInit ,
.BR environPush ,
.BR putenv ,
or
.BR setenv
failed because they were unable to allocate memory for the environment.
.SH CAVEATS
If
.B environ
has been modified without using the library routines, then the internal
shell variables and the shell environment represented by
.B environ
will not be consistent.  Also, since environ entries are dynamically
allocated and freed, modifying those entries without using the library
routines may result in memory trashing and unpredicable behavior.
.SH AUTHORS
These routines were written for GNO primarily by Devin Reade.  They
also contain code fragments from Dave Tribby and James Brookes.
.LP
These routines also contains code is derived from software contributed
to Berkeley by the American National Standards Committee X3, on
Information Processing Systems.
.SH SEE ALSO                  
.BR gsh (1),
.BR sh (1),
.BR execve (2),
.BR environ (7),
.SH HISTORY
The functions
.B setenv
and
.B unsetenv
appeared in Version 7 AT&T UNIX.  The
.B putenv
function appeared in 4.3BSD (Reno).
.LP
The first appearance of these routines for GNO was as part of the
(now superceeded)
.BR lenviron
library.  They were formally incorporated into GNO as of v2.0.6.
These routines are no longer guaranteed to be compatible with the 
ORCA/Shell.
.LP
The functions
.BR environInit ,
.BR environPush ,
and 
.BR environPop
were previously
.BR initenv ,
.BR pushenv ,
and 
.BR popenv ,
respectively.