getenv man page on Mageia

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

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

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

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(3P)
[top]

List of man pages available for Mageia

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