_dupenv_s
, _wdupenv_s
Gets a value from the current environment.
Important
This API cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported in Universal Windows Platform apps.
Syntax
errno_t _dupenv_s(
char **buffer,
size_t *numberOfElements,
const char *varname
);
errno_t _wdupenv_s(
wchar_t **buffer,
size_t *numberOfElements,
const wchar_t *varname
);
Parameters
buffer
Buffer to store the variable's value.
numberOfElements
Size of buffer
.
varname
Environment variable name.
Return value
Zero on success, an error code on failure.
These functions validate their parameters; if buffer
or varname
is NULL
, the invalid parameter handler is invoked as described in Parameter validation. If execution is allowed to continue, the functions set errno
to EINVAL
and return EINVAL
.
If these functions can't allocate enough memory, they set buffer
to NULL
and numberOfElements
to 0, and return ENOMEM
.
Remarks
The _dupenv_s
function searches the list of environment variables for varname
. If the variable is found, _dupenv_s
allocates a buffer and copies the variable's value into the buffer. The buffer's address and length are returned in buffer
and numberOfElements
. Because it allocates the buffer itself, _dupenv_s
provides a more convenient alternative to getenv_s
, _wgetenv_s
.
Note
It's the calling program's responsibility to free the memory by calling free
.
If the variable isn't found, then buffer
is set to NULL
, numberOfElements
is set to 0, and the return value is 0 because this situation isn't considered to be an error condition.
If you aren't interested in the size of the buffer, you can pass NULL
for numberOfElements
.
_dupenv_s
isn't case sensitive in the Windows operating system. _dupenv_s
uses the copy of the environment pointed to by the global variable _environ
to access the environment. See the Remarks in getenv_s
, _wgetenv_s
for a discussion of _environ
.
The value in buffer
is a copy of the environment variable's value; modifying it has no effect on the environment. Use the _putenv_s
, _wputenv_s
function to modify the value of an environment variable.
_wdupenv_s
is a wide-character version of _dupenv_s
; the arguments of _wdupenv_s
are wide-character strings. The _wenviron
global variable is a wide-character version of _environ
. See the Remarks in getenv_s
, _wgetenv_s
for more on _wenviron
.
By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.
Generic-text routine mappings
TCHAR.H routine |
_UNICODE and _MBCS not defined |
_MBCS defined |
_UNICODE defined |
---|---|---|---|
_tdupenv_s |
_dupenv_s |
_dupenv_s |
_wdupenv_s |
Requirements
Routine | Required header |
---|---|
_dupenv_s |
<stdlib.h> |
_wdupenv_s |
<stdlib.h> or <wchar.h> |
For more compatibility information, see Compatibility.
Example
// crt_dupenv_s.c
#include <stdlib.h>
int main( void )
{
char *pValue;
size_t len;
errno_t err = _dupenv_s( &pValue, &len, "pathext" );
if ( err ) return -1;
printf( "pathext = %s\n", pValue );
free( pValue );
err = _dupenv_s( &pValue, &len, "nonexistentvariable" );
if ( err ) return -1;
printf( "nonexistentvariable = %s\n", pValue );
free( pValue ); // It's OK to call free with NULL
}
pathext = .COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.pl
nonexistentvariable = (null)
See also
Process and environment control
Environmental constants
_dupenv_s_dbg
, _wdupenv_s_dbg
getenv_s
, _wgetenv_s
_putenv_s
, _wputenv_s