Compartilhar via


getenv_s, _wgetenv_s

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.

Observação importanteImportante

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.

Observação de cuidadoCuidado

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çãoObservaçã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);
}
  

Equivalência do .NET Framework

System::Environment::GetEnvironmentVariable

Consulte também

Referência

Processo e controle do ambiente

Constantes ambientais

_putenv, _wputenv

_dupenv_s, _wdupenv_s