getenv_s, _wgetenv_s

Obter um valor do ambiente corrente.Essas são sistema autônomo versões de GETENV, _wgetenv com aprimoramentos de segurança conforme descrito em Aprimoramentos de segurança no CRT.

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

• buffer
  Buffer para armazenar a variável e seu valor.

• numberOfElements
  dimensionar de buffer.

• varname
  Nome da variável de ambiente.

Valor de retorno

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

Condições de erro

Qualquer uma das condições de erro acima invocará um manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro. Se a execução for permitida para continuar, as funções conjunto errno para EINVAL e retornar EINVAL.

Além disso, se o buffer for muito pequeno, essas funções retornam ERANGE. Eles não chamar um manipulador de parâmetro inválido.Eles irão escrever o dimensionar do buffer necessário em pReturnValue, permitindo que programas chamar a função novamente com um buffer maior.

Comentários

The getenv_s função na lista de variáveis de ambiente para pesquisa varname. getenv_s não diferencia maiúsculas e minúsculas no sistema operacional Windows. getenv_s e _putenv_s usar a cópia do ambiente apontada pela variável global _environ para acessar o ambiente. getenv_sfunciona somente com as estruturas de dados acessíveis ao em time de execução biblioteca e não no ambiente de "segmento" criado para o processo pelo sistema operacional. Portanto, os programas que usam o envp argumento para principal or wmain pode recuperar informações inválidas.

Não é seguro modificar o valor da variável de ambiente usando o ponteiro retornado em buffer. Use o _putenv_s função para modificar o valor de uma variável de ambiente. O valor de buffer é conjunto como uma seqüência de caracteres vazia se varname não foi encontrado na tabela de ambiente.

_wgetenv_s é uma versão de caractere largo da getenv_s; valor de argumento e retornar _wgetenv_s são seqüências de caracteres largos. The _wenviron variável global é uma versão de caractere largo da _environ.

Em um MBCS programa (por exemplo, em um programa do SBCS ASCII), _wenviron é inicialmente NULL porque o ambiente é composto de seqüências de caractere de multibyte. Em seguida, na primeira telefonar _wputenv, ou na primeira telefonar para _wgetenv_s Se já existir um ambiente (MBCS), um ambiente de seqüência de caractere largos correspondente é criado e, em seguida, é apontado por _wenviron.

Da mesma forma em um Unicode (_wmain) programa, _environ é inicialmente NULL porque o ambiente é composto de seqüências de caractere largos. Em seguida, na primeira telefonar _putenv, ou na primeira telefonar para getenv_s Se já existir um ambiente (Unicode), um ambiente MBCS correspondente é criado e, em seguida, é apontado por _environ.

Quando duas cópias do ambiente (MBCS e Unicode) de existem simultaneamente em um programa, o em time de execução sistema deve manter as duas cópias, resultando em menor time de execução.Por exemplo, sempre que você chamar _putenv, uma telefonar para _wputenv também é executada automaticamente, para que as seqüências de caracteres de dois ambiente correspondem.

Cuidado:

Em raras ocasiões, quando o sistema de time de execução é manter uma versão de Unicode e multibyte versão do ambiente, essas versões do duas ambiente podem não corresponder exatamente.Isso ocorre porque, embora qualquer exclusivo multibyte -seqüência de caractere mapeia para uma seqüência Unicode exclusiva, o mapeamento de uma seqüência de caractere Unicode exclusivo para um multibyte -seqüência de caractere não é necessariamente exclusivo.Para obter mais informações, consulte _environ, _wenviron.

Observação:
O _putenv_s e _getenv_s famílias de funções não são thread-safe. _getenv_s pode retornar um ponteiro de seqüência de caracteres ao mesmo tempo _putenv_s é modificar a seqüência de caracteres, causando falhas aleatórias. Certifique-se de que as chamadas para essas funções estão sincronizadas.

No C++, usando essas funções é simplificado pela sobrecargas de modelo; sobrecargas de podem inferir comprimento do buffer automaticamente, eliminando a necessidade de especificar um argumento de dimensionar.Para obter mais informações, consulte Proteger overloads de modelo.

Mapeamentos de rotina de texto genérica

Para verificar ou alterar o valor de TZ variável de ambiente, uso getenv_s, _putenv e _tzset conforme necessário. Para obter mais informações sobre o TZ, consulte _tzset and see _daylight, fuso horário e _tzname.

Requisitos

Para obter informações adicionais compatibilidade, consulte Compatibilidade na introdução.

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

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

   if( libvar != NULL )
      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*) malloc(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" );

   if( libvar != NULL )
      printf( "New LIB variable is: %s\n", 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

Equivalente do NET Framework

sistema::ambiente::GetEnvironmentVariable

Consulte também

Referência

Processo e ambiente de controle

Constantes ambientais

_putenv, _wputenv

_dupenv_s, _wdupenv_s