getenv_s, _wgetenv_s

Artigo
06/09/2015

Obtém um valor do ambiente atual. Essas versões de getenv, _wgetenv têm aprimoramentos de segurança, como descrito em Recursos de segurança no CRT.

Importante

Não é possível usar essa API em aplicativos executados no Tempo de Execução do Windows.Para obter mais informações, consulte Funções CRT sem suporte pelo /ZW.

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

Parâmetros

pReturnValue
O tamanho do buffer exigido, ou 0 se a variável não for localizado.
buffer
Buffer para armazenar o valor da variável de ambiente.
numberOfElements
Tamanho do buffer.
varname
Nome de variável de ambiente.

Valor de retorno

Zero se bem-sucedido; caso contrário, um código de erro da falha.

Condições de erro

pReturnValue	buffer	numberOfElements	varname	Valor de Retorno
NULL	any	any	any	EINVAL
any	NULL	>0	any	EINVAL
any	any	any	NULL	EINVAL

Qualquer uma dessas condições de erro invoca um manipulador inválido do parâmetro, conforme descrito em Validação do parâmetro. Se a execução puder continuar, essas funções serão definidas errno como EINVAL e retornarão EINVAL.

Além disso, se o buffer for muito pequeno, essas funções ERANGEde retorno. Não invoca um manipulador inválido do parâmetro. Ao gravar o tamanho de buffer necessário em pReturnValue, e habilita assim programas para chamar novamente a função com um buffer maior.

Comentários

A função getenv_s procura varname na lista de variáveis de ambiente. getenv_s não diferencia maiúsculas de minúsculas no sistema operacional Windows. getenv_s e _putenv_s usam a cópia do ambiente que é apontado pela variável global _environ para acessar o ambiente. getenv_s funciona apenas nas estruturas de dados que são acessíveis à biblioteca de tempo de execução e não no ambiente “bucket” criado para o processo pelo sistema operacional. Consequentemente, os programas que usam o argumento de envp a principal ou a wmain podem recuperar informações inválidas.

_wgetenv_s é uma versão de ampla caractere de getenv_s; o argumento e o valor de retorno de _wgetenv_s são cadeias de caracteres de ampla caractere. A variável global _wenviron é uma versão de caractere largo de _environ.

Em um programa de MBCS (por exemplo, em um programa de SBCS ASCII), _wenviron é inicialmente NULL porque o ambiente é composto de cadeias de caracteres de multibyte- caractere. Em seguida, na primeira chamada a _wputenv, ou na primeira chamada a _wgetenv_s, se um ambiente de MBCS () já existir, um ambiente correspondente da cadeia de caracteres de ampla caractere é criado e apontado por _wenviron.

De maneira semelhante em um programa Unicode (_wmain), _environ é inicialmente NULL porque o ambiente é composto de cadeias de caracteres de ampla caractere. Em seguida, na primeira chamada a _putenv, ou na primeira chamada a getenv_s se o ambiente de (Unicode) já existir, um ambiente correspondente de MBCS é criado e apontado por _environ.

Quando duas cópias de ambiente (MBCS e Unicode) existem simultaneamente em um programa, o sistema de tempo de execução deve manter ambas as cópias, e isso causa tempos de execução mais lentos. Por exemplo, quando você chama _putenv, uma chamada a _wputenv também é executado automaticamente para que as duas cadeias de caracteres de ambiente correspondam.

Aviso

Em poucas instâncias, quando o sistema de tempo de execução está mantendo uma versão Unicode e uma versão multibyte de ambiente, as duas versões de ambiente podem não corresponder exatamente.Isso ocorre porque, embora nenhum mapas exclusivos da cadeia de caracteres de multibyte- caracteres em uma cadeia de caracteres exclusiva Unicode, o mapeamento de uma cadeia de caracteres Unicode exclusivo em uma cadeia de caracteres de multibyte- caractere não são necessariamente exclusivos.Para obter mais informações, consulte _environ, _wenviron.

Dica

As famílias de funções _putenv_s e _getenv_s não são thread-safe._getenv_s poderia retornar um ponteiro de cadeia de caracteres quando _putenv_s alterar as falhas aleatórios de cadeia de caracteres e assim a causa.Certifique-se de que as chamadas para essas funções sejam sincronizadas.

Em C++, o uso dessas funções é simplificado por sobrecargas do modelo; as sobrecargas pode deduzir o comprimento do buffer automaticamente e assim eliminar a necessidade de especificar um argumento de tamanho. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Mapeamentos da rotina de texto genérico

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_MBCS definido	_UNICODE definido
_tgetenv_s	getenv_s	getenv_s	_wgetenv_s

Para verificar ou alterar o valor da variável de ambiente de TZ , use getenv_s, de _putenv, e de _tzset, conforme necessário. Para obter mais informações sobre como TZ, consulte _tzset e _daylight, _dstbias, _timezone e _tzname.

Requisitos

Rotina	Cabeçalho necessário
getenv_s	<stdlib.h>
_wgetenv_s	<stdlib.h> ou <wchar.h>

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

Exemplo

// 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");
   if (requiredSize == 0)
   {
      printf("LIB doesn't exist!\n");
      exit(1);
   }

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

   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*) realloc(libvar, 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" );

   printf( "New LIB variable is: %s\n", libvar );

   free(libvar);
}