_dupenv_s, _wdupenv_s

Obtém um valor do ambiente atual.

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.

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

Requisitos

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