_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.

Sintaxe

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

Parâmetros

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

Valor retornado

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, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

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.

Requisitos

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 processo e ambiente
getenv, _wgetenv
_searchenv, _wsearchenv