Partilhar via

getenv_s, _wgetenv_s

  • Artigo

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.

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

pReturnValue buffer numberOfElements varname Valor de retorno
NULL any qualquer qualquer EINVAL
any NULL >0 any EINVAL
qualquer qualquer any NULL EINVAL

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.

Cuidado

Em casos raros, quando o sistema de tempo de execução mantém uma versão Unicode e uma versão multibyte do ambiente, as duas versões de ambiente podem não corresponder exatamente. Isso acontece porque, embora qualquer cadeia de caracteres multibyte exclusiva seja mapeada para uma cadeia de caracteres Unicode exclusiva, o mapeamento de uma cadeia de caracteres Unicode exclusiva para uma cadeia de caracteres multibyte não é necessariamente exclusivo. Para obter mais informações, consulte _environe _wenviron.

Observação

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 enquanto _putenv_s está modificando a cadeia de caracteres e, portanto, causar falhas aleatórias. As chamadas para essas funções devem estar sincronizadas.

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

Rotina TCHAR.H _UNICODE e _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, _putenv e _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 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