getenv_s, _wgetenv_s

Obtém um valor do ambiente atual. Essas versões do , _wgetenvtêm aprimoramentos degetenv segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

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 necessário ou 0 se a variável não for encontrada.

buffer
Buffer para armazenar o valor da variável de ambiente.

numberOfElements
Tamanho de buffer.

varname
Nome da variável de ambiente.

Valor retornado

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

Condições de erro

Qualquer uma dessas condições de erro invoca um manipulador de parâmetro inválido, 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.

Além disso, se o buffer for muito pequeno, essas funções retornarão ERANGE. Elas não invocam um manipulador de parâmetro inválido. Elas gravam o tamanho do buffer necessário em pReturnValue e, portanto, habilitam programas a chamarem a função novamente com um buffer maior.

Comentários

A função getenv_s pesquisa 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 apontado pela variável global _environ para acessar o ambiente. getenv_s funciona somente nas estruturas de dados que são acessíveis para a biblioteca em tempo de execução e não no "segmento" de ambiente que é criado para o processo pelo sistema operacional. Portanto, programas que usam o argumento envp para main or wmain podem recuperar informações inválidas.

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

Em um programa MBCS (por exemplo, em um programa ASCII SBCS), _wenviron é inicialmente NULL porque o ambiente é composto por cadeias de caracteres multibyte. Então, na primeira chamada para _wputenv ou na primeira chamada para _wgetenv_s se um ambiente (MBCS) já existir, um ambiente correspondente de cadeia de caracteres largos será criado e apontado por _wenviron.

De forma semelhante, em um programa Unicode (_wmain), _environ é inicialmente NULL porque o ambiente é composto por cadeias de caracteres largos. Então, na primeira chamada para _putenv ou na primeira chamada para getenv_s se um ambiente (Unicode) já existir, um ambiente MBCS correspondente será criado e apontado por _environ.

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

No C++, o uso dessas funções é simplificado por sobrecargas de modelo. As sobrecargas podem inferir o tamanho do buffer automaticamente, eliminando a necessidade de especificar um argumento de tamanho. Para obter mais informações, consulte Sobrecargas de modelo seguras.

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

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

Requisitos

Para obter informações 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);
}

Original LIB variable is: c:\vctools\lib;c:\vctools\atlmfc\lib;c:\vctools\PlatformSDK\lib;c:\vctools\Visual Studio SDKs\DIA Sdk\lib;c:\vctools\Visual Studio SDKs\BSC Sdk\lib
New LIB variable is: c:\mylib;c:\yourlib

Confira também

Controle de processo e ambiente
Constantes ambientais
_putenv, _wputenv
_dupenv_s, _wdupenv_s