.\" 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 . 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 .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.