mirror of
https://github.com/GnoConsortium/gno.git
synced 2024-09-11 14:54:54 +00:00
216 lines
6.1 KiB
Groff
216 lines
6.1 KiB
Groff
.\" 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 v7. 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.
|