1 files changed, 157 insertions, 0 deletions
diff --git a/man3p/getenv.3p b/man3p/getenv.3p
new file mode 100644
index 000000000..ddccb22a5
--- /dev/null
+++ b/man3p/getenv.3p
@@ -0,0 +1,157 @@
+.\" 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 .