_dupenv_s, _wdupenv_s

Obtém um valor do ambiente atual.

Importante

Esta API não pode ser usada em aplicativos executados no Windows Runtime. Para obter mais informações, confira Funções do CRT sem suporte em aplicativos da Plataforma Universal do Windows.

Sintaxe

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
);

Parâmetros

buffer
Buffer para armazenar o valor da variável.

numberOfElements
Tamanho de buffer.

varname
Nome da variável de ambiente.

Valor retornado

Zero em caso de êxito; código de erro em caso de falha.

Essas funções validam seus parâmetros; if buffer ou varname is NULL, o manipulador de parâmetro inválido é invocado conforme descrito em Validação de parâmetro. Se a execução puder continuar, as funções definirão errno como EINVAL e retornarão EINVAL.

Se essas funções não puderem alocar memória suficiente, elas serão definidas buffer como NULL e numberOfElements como 0 e retornarão ENOMEM.

Comentários

A função _dupenv_s pesquisa varname na lista de variáveis de ambiente. Se a variável for encontrada, _dupenv_s alocará um buffer e copiará o valor da variável para o buffer. O endereço e o tamanho do buffer são retornados em buffer e numberOfElements. Como ele aloca o próprio buffer, _dupenv_s fornece uma alternativa mais conveniente para getenv_s, _wgetenv_s.

Observação

É responsabilidade do programa de chamada liberar a memória chamando free.

Se a variável não for encontrada, então buffer é definido como NULL, numberOfElements é definido como 0 e o valor retornado é 0 porque essa situação não é considerada uma condição de erro.

Se você não estiver interessado no tamanho do buffer, poderá passar NULL por numberOfElements.

_dupenv_s não diferencia maiúsculas de minúsculas no sistema operacional Windows. _dupenv_s usa a cópia do ambiente apontado pela variável global _environ para acessar o ambiente. Consulte os Comentários em getenv_s, _wgetenv_s para ver uma discussão de _environ.

O valor em buffer é uma cópia do valor da variável de ambiente. Modificá-lo não afeta o ambiente. Use a função _putenv_s, _wputenv_s para modificar o valor de uma variável de ambiente.

_wdupenv_s é uma versão de caractere largo de _dupenv_s. Os argumentos de _wdupenv_s são cadeias de caracteres largas. A variável global _wenviron é uma versão de caractere largo de _environ. Consulte os Comentários em getenv_s, _wgetenv_s para obter mais informações em _wenviron.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tdupenv_s	_dupenv_s	_dupenv_s	_wdupenv_s

Requisitos

Rotina	Cabeçalho necessário
_dupenv_s	<stdlib.h>
_wdupenv_s	<stdlib.h> ou <wchar.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// 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)

Confira também

Controle de processo e ambiente
Constantes ambientais
_dupenv_s_dbg, _wdupenv_s_dbg
getenv_s, _wgetenv_s
_putenv_s, _wputenv_s