Função GetEnvironmentVariableW (processenv.h)

Artigo
11/20/2024

Recupera o conteúdo da variável especificada do bloco de ambiente do processo de chamada.

Sintaxe

DWORD GetEnvironmentVariableW(
  [in, optional]  LPCWSTR lpName,
  [out, optional] LPWSTR  lpBuffer,
  [in]            DWORD   nSize
);

Parâmetros

[in, optional] lpName

O nome da variável de ambiente.

[out, optional] lpBuffer

Um ponteiro para um buffer que recebe o conteúdo da variável de ambiente especificada como uma cadeia de caracteres terminada em nulo.

O tamanho máximo de uma variável de ambiente definida pelo usuário é de 32.767 caracteres. Não há nenhuma limitação técnica no tamanho do bloco de ambiente. No entanto, há limites práticos dependendo do mecanismo usado para acessar o bloco. Por exemplo, um arquivo em lote não pode definir uma variável que seja maior que o comprimento máximo da linha de comando. Para obter mais informações, consulte variáveis de ambiente.

[in] nSize

O tamanho do buffer apontado pelo parâmetro lpBuffer, incluindo o caractere de terminação nula, em caracteres.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será o número de caracteres armazenados no buffer apontado por lpBuffer, não incluindo o caractere nulo de encerramento.

Se lpBuffer não for grande o suficiente para manter os dados, o valor retornado será o tamanho do buffer, em caracteres, necessário para manter a cadeia de caracteres e seu caractere nulo de terminação e o conteúdo de lpBuffer são indefinidos.

Se a função falhar, o valor retornado será zero. Se a variável de ambiente especificada não tiver sido encontrada no bloco de ambiente, GetLastError retornará ERROR_ENVVAR_NOT_FOUND.

Observações

Essa função pode recuperar uma variável de ambiente do sistema ou uma variável de ambiente do usuário.

Exemplos

Para obter um exemplo, consulte Alterando variáveis de ambiente.

Nota

O cabeçalho processenv.h define GetEnvironmentVariable como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	processenv.h (inclua Windows.h no Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

variáveis de ambiente

GetEnvironmentStrings

SetEnvironmentVariable

Compartilhar via