mirror of https://github.com/mkerrisk/man-pages
158 lines
6.1 KiB
Plaintext
158 lines
6.1 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "GETENV" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" getenv
|
|
.SH NAME
|
|
getenv \- get value of an environment variable
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <stdlib.h>
|
|
.br
|
|
.sp
|
|
char *getenv(const char *\fP\fIname\fP\fB);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIgetenv\fP() function shall search the environment of the calling
|
|
process (see the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables) for the
|
|
environment
|
|
variable \fIname\fP if it exists and return a pointer to the value
|
|
of the environment variable. If the specified environment
|
|
variable cannot be found, a null pointer shall be returned. The application
|
|
shall ensure that it does not modify the string pointed
|
|
to by the \fIgetenv\fP() function.
|
|
.LP
|
|
The string pointed to may be overwritten by a subsequent call to \fIgetenv\fP(),
|
|
\fIsetenv\fP(), or \fIunsetenv\fP(), but shall not be overwritten
|
|
by a call to any other function in this volume
|
|
of IEEE\ Std\ 1003.1-2001.
|
|
.LP
|
|
If
|
|
the application modifies \fIenviron\fP or the pointers to which it
|
|
points, the behavior of \fIgetenv\fP() is undefined.
|
|
.LP
|
|
The \fIgetenv\fP() function need not be reentrant. A function that
|
|
is not required to be reentrant is not required to be
|
|
thread-safe.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, \fIgetenv\fP() shall return a pointer
|
|
to a string containing the \fIvalue\fP for the specified
|
|
\fIname\fP. If the specified \fIname\fP cannot be found in the environment
|
|
of the calling process, a null pointer shall be
|
|
returned.
|
|
.LP
|
|
The return value from \fIgetenv\fP() may point to static data which
|
|
may be overwritten by subsequent calls to \fIgetenv\fP(),
|
|
\fIsetenv\fP(), or \fIunsetenv\fP().
|
|
.LP
|
|
On XSI-conformant systems, the return value from \fIgetenv\fP() may
|
|
point to static data which may also be overwritten by
|
|
subsequent calls to \fIputenv\fP().
|
|
.SH ERRORS
|
|
.LP
|
|
No errors are defined.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.SS Getting the Value of an Environment Variable
|
|
.LP
|
|
The following example gets the value of the \fIHOME\fP environment
|
|
variable.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <stdlib.h>
|
|
\&...
|
|
const char *name = "HOME";
|
|
char *value;
|
|
.sp
|
|
|
|
value = getenv(name);
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
The \fIclearenv\fP() function was considered but rejected. The \fIputenv\fP()
|
|
function
|
|
has now been included for alignment with the Single UNIX Specification.
|
|
.LP
|
|
The \fIgetenv\fP() function is inherently not reentrant because it
|
|
returns a value pointing to static data.
|
|
.LP
|
|
Conforming applications are required not to modify \fIenviron\fP directly,
|
|
but to use only the functions described here to
|
|
manipulate the process environment as an abstract object. Thus, the
|
|
implementation of the environment access functions has complete
|
|
control over the data structure used to represent the environment
|
|
(subject to the requirement that \fIenviron\fP be maintained as
|
|
a list of strings with embedded equal signs for applications that
|
|
wish to scan the environment). This constraint allows the
|
|
implementation to properly manage the memory it allocates, either
|
|
by using allocated storage for all variables (copying them on the
|
|
first invocation of \fIsetenv\fP() or \fIunsetenv\fP()), or keeping
|
|
track of which strings are currently in allocated space and which
|
|
are not, via a separate table or some other means. This enables the
|
|
implementation to free any allocated space used by strings (and
|
|
perhaps the pointers to them) stored in \fIenviron\fP when \fIunsetenv\fP()
|
|
is called. A
|
|
C runtime start-up procedure (that which invokes \fImain\fP() and
|
|
perhaps initializes \fIenviron\fP) can also initialize a flag
|
|
indicating that none of the environment has yet been copied to allocated
|
|
storage, or that the separate table has not yet been
|
|
initialized.
|
|
.LP
|
|
In fact, for higher performance of \fIgetenv\fP(), the implementation
|
|
could also maintain a separate copy of the environment in
|
|
a data structure that could be searched much more quickly (such as
|
|
an indexed hash table, or a binary tree), and update both it and
|
|
the linear list at \fIenviron\fP when \fIsetenv\fP() or \fIunsetenv\fP()
|
|
is invoked.
|
|
.LP
|
|
Performance of \fIgetenv\fP() can be important for applications which
|
|
have large numbers of environment variables. Typically,
|
|
applications like this use the environment as a resource database
|
|
of user-configurable parameters. The fact that these variables
|
|
are in the user's shell environment usually means that any other program
|
|
that uses environment variables (such as \fIls\fP, which attempts
|
|
to use \fICOLUMNS ),\fP or really almost any utility ( \fILANG ,\fP
|
|
\fILC_ALL ,\fP and so on) is similarly slowed down by the linear search
|
|
through the variables.
|
|
.LP
|
|
An implementation that maintains separate data structures, or even
|
|
one that manages the memory it consumes, is not currently
|
|
required as it was thought it would reduce consensus among implementors
|
|
who do not want to change their historical
|
|
implementations.
|
|
.LP
|
|
The POSIX Threads Extension states that multi-threaded applications
|
|
must not modify \fIenviron\fP directly, and that
|
|
IEEE\ Std\ 1003.1-2001 is providing functions which such applications
|
|
can use in the future to manipulate the environment
|
|
in a thread-safe manner. Thus, moving away from application use of
|
|
\fIenviron\fP is desirable from that standpoint as well.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIexec\fP() , \fIputenv\fP() , \fIsetenv\fP() , \fIunsetenv\fP()
|
|
, the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables, \fI<stdlib.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|