getenv man page on YellowDog

Man page or keyword search:  
man Server   18644 pages
apropos Keyword Search (all sections)
Output format
YellowDog logo
[printable version]

GETENV(P)		   POSIX Programmer's Manual		     GETENV(P)

NAME
       getenv - get value of an environment variable

SYNOPSIS
       #include <stdlib.h>

       char *getenv(const char *name);

DESCRIPTION
       The  getenv()  function	shall  search  the  environment of the calling
       process (see the Base Definitions volume of IEEE Std 1003.1-2001, Chap‐
       ter  8,	Environment Variables) for the environment variable name 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 getenv() function.

       The  string  pointed  to	 may  be  overwritten  by a subsequent call to
       getenv(), setenv(), or unsetenv(),  but shall not be overwritten	 by  a
       call to any other function in this volume of IEEE Std 1003.1-2001.

       If the application modifies environ or the pointers to which it points,
       the behavior of getenv() is undefined.

       The getenv() function need not be reentrant. A  function	 that  is  not
       required to be reentrant is not required to be thread-safe.

RETURN VALUE
       Upon successful completion, getenv() shall return a pointer to a string
       containing the value for the specified name. If the specified name can‐
       not  be found in the environment of the calling process, a null pointer
       shall be returned.

       The return value from getenv() may point to static data	which  may  be
       overwritten by subsequent calls to getenv(), setenv(), or unsetenv().

       On  XSI-conformant systems, the return value from getenv() may point to
       static data which may  also  be	overwritten  by	 subsequent  calls  to
       putenv().

ERRORS
       No errors are defined.

       The following sections are informative.

EXAMPLES
   Getting the Value of an Environment Variable
       The following example gets the value of the HOME environment variable.

	      #include <stdlib.h>
	      ...
	      const char *name = "HOME";
	      char *value;

	      value = getenv(name);

APPLICATION USAGE
       None.

RATIONALE
       The clearenv() function was considered but rejected. The putenv() func‐
       tion has now been included for alignment with the Single UNIX  Specifi‐
       cation.

       The  getenv() function is inherently not reentrant because it returns a
       value pointing to static data.

       Conforming applications are required not to  modify  environ  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 struc‐
       ture used to represent the environment (subject to the requirement that
       environ	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 setenv() or unsetenv()), 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 environ when unsetenv() is called. A C runtime start-up
       procedure (that which invokes main() and perhaps	 initializes  environ)
       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.

       In  fact,  for higher performance of getenv(), 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 ta‐
       ble, or a binary tree), and update both it and the linear list at envi‐
       ron when setenv() or unsetenv() is invoked.

       Performance  of	getenv()  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 envi‐
       ronment	usually	 means	that  any  other program that uses environment
       variables (such as ls, which attempts  to  use  COLUMNS	),  or	really
       almost  any  utility  (	LANG , LC_ALL , and so on) is similarly slowed
       down by the linear search through the variables.

       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.

       The  POSIX  Threads  Extension  states that multi-threaded applications
       must not modify environ directly, and that IEEE Std 1003.1-2001 is pro‐
       viding  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 environ is desirable from that standpoint as
       well.

FUTURE DIRECTIONS
       None.

SEE ALSO
       exec() , putenv() , setenv() , unsetenv() , the Base Definitions volume
       of IEEE Std 1003.1-2001, Chapter 8, Environment Variables, <stdlib.h>

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 .

IEEE/The Open Group		     2003			     GETENV(P)
[top]

List of man pages available for YellowDog

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net