getenv, _wgetenv
Obtém um valor do ambiente atual. Versões mais seguras dessas funções estão disponíveis; confira getenv_s, _wgetenv_s.
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
char *getenv(
const char *varname
);
wchar_t *_wgetenv(
const wchar_t *varname
);
Parâmetros
varname
Nome da variável de ambiente.
Valor retornado
Retorna um ponteiro para a entrada da tabela de ambiente que contém varname. Não é seguro modificar o valor da variável de ambiente usando o ponteiro retornado. Use a função _putenv para modificar o valor de uma variável de ambiente. O valor retornado é NULL if varname não for encontrado na tabela de ambiente.
Comentários
A função getenv pesquisa varname na lista de variáveis de ambiente. getenv não diferencia maiúsculas de minúsculas no sistema operacional Windows. getenv e _putenv usam a cópia do ambiente apontado pela variável global _environ para acessar o ambiente. getenv funciona somente nas estruturas de dados acessíveis para a biblioteca em tempo de execução e não no "segmento" de ambiente criado para o processo pelo sistema operacional. Portanto, programas que usam o argumento envp para main ou wmain podem recuperar informações inválidas.
Se varname for NULL, essa função invocará um manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro. Se a execução puder continuar, essa função definirá errno para EINVAL e retornará NULL.
_wgetenv é uma versão de caractere largo de getenv; o argumento e o valor retornado de _wgetenv 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 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 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) existirem simultaneamente em um programa, o sistema de tempo de execução deverá manter as duas cópias, fazendo com que o tempo de execução fique mais lento. Por exemplo, sempre que 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 e _getenv não são thread-safe. _getenv poderia retornar um ponteiro de cadeia de caracteres enquanto _putenv está modificando a cadeia de caracteres, causando falhas aleatórias. As chamadas para essas funções devem estar sincronizadas.
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 |
getenv |
getenv |
_wgetenv |
Para verificar ou alterar o valor da variável de ambiente TZ, use getenv, _putenv e _tzset, conforme necessário. Para obter mais informações sobre TZ, confira _tzset e _daylight, timezone e _tzname.
Requisitos
| Rotina | Cabeçalho necessário |
|---|---|
getenv |
<stdlib.h> |
_wgetenv |
<stdlib.h> ou <wchar.h> |
Para obter informações sobre compatibilidade, consulte Compatibilidade.
Exemplo
// crt_getenv.c
// compile with: /W3
// This program uses getenv 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;
// Get the value of the LIB environment variable.
libvar = getenv( "LIB" ); // C4996
// Note: getenv is deprecated; consider using getenv_s instead
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( "LIB=c:\\mylib;c:\\yourlib" ); // C4996
// Note: _putenv is deprecated; consider using putenv_s instead
// Get new value.
libvar = getenv( "LIB" ); // C4996
if( libvar != NULL )
printf( "New LIB variable is: %s\n", libvar );
}
Original LIB variable is: C:\progra~1\devstu~1\vc\lib
New LIB variable is: c:\mylib;c:\yourlib
Confira também
Controle de processo e ambiente
_putenv, _wputenv
Constantes ambientais