getenv_s, _wgetenv_s

Artigo
03/12/2013

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

Importante
Este API não pode ser usado em aplicativos executados em Tempo de Execução do Windows.Para obter mais informações, consulte Funções de CRT não suportadas com /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 que é necessária, ou 0 se a variável não for encontrado.
buffer
Buffer para armazenar o valor da variável de ambiente.
numberOfElements
Tamanho de buffer.
varname
Nome da variável de ambiente.

Valor de retorno

Zero se com êxito; caso contrário, um código de erro em caso de falha.

Condições de erro

pReturnValue	buffer	numberOfElements	varname	Retornar valor
NULL	alguns	alguns	alguns	EINVAL
alguns	NULL	>0	alguns	EINVAL
alguns	alguns	alguns	NULL	EINVAL

Uma destas condições de erro chamam um manipulador de parâmetro inválido, como descrito em Validação de parâmetro.Se a execução é permitida continuar, errno definir funções a EINVAL e a EINVALde retorno.

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

Comentários

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

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

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

Da mesma forma em um programa Unicode (_wmain), _environ é inicialmente NULL porque o ambiente é composta de cadeias de caracteres de largo- 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 então 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 as duas cópias, e isso faz com que um tempo de execução mais lentos.Por exemplo, quando você chama _putenv, uma chamada a _wputenv é executado também automaticamente de modo que as duas cadeias de caracteres de ambiente coincidam.

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

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

Observação
As famílias de _putenv_s e de _getenv_s de funções não são com segurança._getenv_s pode retornar um ponteiro de cadeia de caracteres quando _putenv_s alterar falhas aleatórias de cadeia de caracteres e causa dessa maneira.Certifique-se de que as chamadas a essas funções são sincronizados.

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

Mapeamentos da rotina de Genérico- texto

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

Para verificar ou alterar o valor da variável de ambiente TZ , use getenv_s, de _putenv, e de _tzset, conforme necessário.Para obter mais informações sobre 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 informações extras de 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);
}