_putenv, _wputenv

Cria, modifica ou remove as variáveis de ambiente. Versões mais seguras dessas funções estão disponíveis; confira _putenv_s, _wputenv_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

int _putenv(
   const char *envstring
);
int _wputenv(
   const wchar_t *envstring
);

Parâmetros

envstring
Definição de cadeia de caracteres de ambiente.

Retornar valor

As funções retornam 0 se forem bem-sucedidas ou -1 se houver um erro.

Comentários

A função _putenv adiciona novas variáveis de ambiente ou modifica os valores de variáveis de ambiente existentes. Variáveis de ambiente definem o ambiente no qual um processo é executado (por exemplo, o caminho de pesquisa padrão para bibliotecas a ser vinculado a um programa). A função _wputenv é uma versão de caractere largo da função _putenv; o argumento envstring para _wputenv é uma cadeia de caracteres larga.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Mapeamentos de rotina de texto genérico

Rotina Tchar.h	_UNICODE and _MBCS não definido	_MBCS definido	_UNICODE definido
_tputenv	_putenv	_putenv	_wputenv

O argumento envstring deve ser um ponteiro para uma cadeia de caracteres no formato varname=value_string, em que varname é o nome da variável de ambiente a ser adicionada ou modificada e value_string é o valor da variável. Se varname já fizer parte do ambiente, seu valor será substituído por value_string; caso contrário, a nova variável varname e seu valor value_string serão adicionados ao ambiente. Você pode remover uma variável do ambiente especificando uma value_string vazia ou, em outras palavras, especificando apenas varname=.

_putenv e _wputenv afetam apenas o ambiente que é local para o processo atual, você não pode usá-los para modificar o ambiente de nível de comando. Ou seja, essas funções operam apenas em estruturas de dados acessíveis à biblioteca de tempo de execução. Eles não operam no segmento de ambiente criado para um processo pelo sistema operacional. Quando o processo atual termina, o ambiente é revertido para o nível do processo de chamada (que, na maioria dos casos, é o nível do sistema operacional). No entanto, o ambiente modificado pode ser passado para novos processos criados por _spawn, _exec ou system e esses novos processos obtém os novos itens que são adicionados por _putenv e _wputenv.

Não altere uma entrada de ambiente diretamente: em vez disso, use _putenv ou _wputenv para alterá-la. Em especial, liberar elementos da matriz global _environ[] diretamente pode fazer com que a memória inválida seja resolvida.

_getenv e _putenv usam a variável global _environ para acessar a tabela de ambiente; _wgetenv e _wputenv usam _wenviron. _putenv e _wputenv podem alterar o valor de _environ e _wenviron, invalidando, portanto, o argumento _envp para main e o argumento _wenvp para wmain. Portanto, é mais seguro usar _environ ou _wenviron para acessar as informações de ambiente. Para obter mais informações sobre a relação de _putenv e _wputenv com as variáveis globais, confira _environ,_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.

Requisitos

Rotina	Cabeçalho necessário
_putenv	<stdlib.h>
_wputenv	<stdlib.h> ou <wchar.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

Para encontrar um exemplo de como usar _putenv, confira getenv, _wgetenv.

Confira também

Controle de processos e ambientes
getenv, _wgetenv
_searchenv, _wsearchenv