Export (0) Print
Expand All
div
eof
Expand Minimize

getenv_s, _wgetenv_s 

Get a value from the current environment. These are versions of getenv, _wgetenv with security enhancements as described in Security Enhancements in the CRT.


errno_t getenv_s( 
   size_t *pReturnValue,
   char* buffer,
   size_t numberOfElements,
   const char *varname 
);
errno_t _wgetenv_s( 
   size_t *pReturnValue,
   wchar_t *buffer,
     size_t numberOfElements,
   const wchar_t *varname 
);
template <size_t size>
errno_t getenv_s( 
   size_t *pReturnValue,
   char (&buffer)[size],
   const char *varname 
); // C++ only
template <size_t size>
errno_t _wgetenv_s( 
   size_t *pReturnValue,
   wchar_t (&buffer)[size],
   const wchar_t *varname 
); // C++ only

Parameters

pReturnValue

The buffer size needed, or 0 if the variable is not found.

buffer

Buffer to store the variable and its value.

numberOfElements

Size of buffer.

varname

Environment variable name.

Zero if successful, an error code on failure.

Error Conditions
pReturnValue buffer numberOfElements varname Return Value

NULL

any

any

any

EINVAL

any

NULL

>0

any

EINVAL

any

any

any

NULL

EINVAL

Any of the above error conditions will invoke an invalid parameter handler, as described in Parameter Validation. If execution is allowed to continue, the functions set errno to EINVAL and return EINVAL.

Also, if the buffer is too small, these functions return ERANGE. They do not invoke an invalid parameter handler. They will write out the required buffer size in pReturnValue, enabling programs to call the function again with a larger buffer.

The getenv_s function searches the list of environment variables for varname. getenv_s is not case sensitive in the Windows operating system. getenv_s and _putenv_s use the copy of the environment pointed to by the global variable _environ to access the environment. getenv_s operates only on the data structures accessible to the run-time library and not on the environment "segment" created for the process by the operating system. Therefore, programs that use the envp argument to main or wmain may retrieve invalid information.

It is not safe to modify the value of the environment variable using the pointer returned in buffer. Use the _putenv_s function to modify the value of an environment variable. The value of buffer is set to an empty string if varname is not found in the environment table.

_wgetenv_s is a wide-character version of getenv_s; the argument and return value of _wgetenv_s are wide-character strings. The _wenviron global variable is a wide-character version of _environ.

In an MBCS program (for example, in an SBCS ASCII program), _wenviron is initially NULL because the environment is composed of multibyte-character strings. Then, on the first call to _wputenv, or on the first call to _wgetenv_s if an (MBCS) environment already exists, a corresponding wide-character string environment is created and is then pointed to by _wenviron.

Similarly in a Unicode (_wmain) program, _environ is initially NULL because the environment is composed of wide-character strings. Then, on the first call to _putenv, or on the first call to getenv_s if a (Unicode) environment already exists, a corresponding MBCS environment is created and is then pointed to by _environ.

When two copies of the environment (MBCS and Unicode) exist simultaneously in a program, the run-time system must maintain both copies, resulting in slower execution time. For example, whenever you call _putenv, a call to _wputenv is also executed automatically, so that the two environment strings correspond.

Caution noteCaution

In rare instances, when the run-time system is maintaining both a Unicode version and a multibyte version of the environment, these two environment versions may not correspond exactly. This is because, although any unique multibyte-character string maps to a unique Unicode string, the mapping from a unique Unicode string to a multibyte-character string is not necessarily unique. For more information, see _environ, _wenviron.

NoteNote

The _putenv_s and _getenv_s families of functions are not thread-safe. _getenv_s could return a string pointer while _putenv_s is modifying the string, causing random failures. Make sure that calls to these functions are synchronized.

In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see Secure Template Overloads.

Generic-Text Routine Mappings
TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined

_tgetenv_s

getenv_s

getenv_s

_wgetenv_s

To check or change the value of the TZ environment variable, use getenv_s, _putenv and _tzset as necessary. For more information about TZ, see _tzset and see _daylight, timezone, and _tzname.

Routine Required header Compatibility

getenv_s

<stdlib.h>

Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003

_wgetenv_s

<stdlib.h> or <wchar.h>

Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003

For additional compatibility information, see Compatibility in the Introduction.

// crt_getenv_s.c
// This program uses getenv_s to retrieve
// the LIB environment variable and then uses
// _putenv to change it to a new value.
 
#include <stdlib.h>
#include <stdio.h>

int main( void )
{
   char* libvar;
   size_t requiredSize;

   getenv_s( &requiredSize, NULL, 0, "LIB");

   libvar = (char*) malloc(requiredSize * sizeof(char));
   if (!libvar)
   {
      printf("Failed to allocate memory!\n");
      exit(1);
   }

   // Get the value of the LIB environment variable.
   getenv_s( &requiredSize, libvar, requiredSize, "LIB" );

   if( libvar != NULL )
      printf( "Original LIB variable is: %s\n", libvar );

   // Attempt to change path. Note that this only affects
   // the environment variable of the current process. The command
   // processor's environment is not changed.
   _putenv_s( "LIB", "c:\\mylib;c:\\yourlib" );

   getenv_s( &requiredSize, NULL, 0, "LIB");

   libvar = (char*) malloc(requiredSize * sizeof(char));
   if (!libvar)
   {
      printf("Failed to allocate memory!\n");
      exit(1);
   }

   // Get the new value of the LIB environment variable. 
   getenv_s( &requiredSize, libvar, requiredSize, "LIB" );

   if( libvar != NULL )
      printf( "New LIB variable is: %s\n", libvar );
}

Sample Output

Original LIB variable is: c:\vctools\lib;c:\vctools\atlmfc\lib;c:\vctools\PlatformSDK\lib;c:\vctools\Visual Studio SDKs\DIA Sdk\lib;c:\vctools\Visual Studio SDKs\BSC Sdk\lib
New LIB variable is: c:\mylib;c:\yourlib

Community Additions

ADD
Show:
© 2014 Microsoft