_putenv_s, _wputenv_s

Cria, modifica ou remove as variáveis de ambiente. Essas funções são versões do , que têm aprimoramentos de segurança, conforme descrito em Recursos de _putenvsegurança na CRT. _wputenv

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

errno_t _putenv_s(
   const char *varname,
   const char *value_string
);
errno_t _wputenv_s(
   const wchar_t *varname,
   const wchar_t *value_string
);

Parâmetros

varname
O nome da variável de ambiente.

value_string
O valor a ser definido para a variável de ambiente.

Retornar valor

Retorna 0 se for bem-sucedido ou um código de erro.

Condições de erro

varname	value_string	Retornar valor
NULL	qualquer	EINVAL
qualquer	NULL	EINVAL

Se ocorrer uma das condições de erro, essas funções invocarão um manipulador de parâmetros inválido, conforme descrito em Validação de parâmetro. Se a execução puder continuar, essas funções retornarão EINVAL e definirão errno para EINVAL.

Comentários

A função _putenv_s 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_s é uma versão de caractere largo da função _putenv_s; o argumento envstring para _wputenv_s é 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 e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tputenv_s	_putenv_s	_putenv_s	_wputenv_s

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 value_string são adicionadas ao ambiente. Você pode remover uma variável do ambiente especificando uma cadeia de caracteres vazia (isto é, "") para value_string.

_putenv_s e _wputenv_s 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. Essas funções operam somente nas estruturas de dados que são acessíveis para a biblioteca em tempo de execução e não no “segmento” de ambiente que o sistema operacional cria para um processo. Quando o processo atual termina, o ambiente será 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_s e _wputenv_s.

Não altere uma entrada de ambiente diretamente. Em vez disso, use _putenv_s ou _wputenv_s 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_s usam a variável global _environ para acessar a tabela de ambiente; _wgetenv e _wputenv_s usam _wenviron. _putenv_s e _wputenv_s 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_s e _wputenv_s com as variáveis globais, confira _environ,_wenviron.

Observação

As famílias de funções _putenv_s e _getenv_s não são thread-safe. _getenv_s poderia retornar um ponteiro de cadeia de caracteres enquanto _putenv_s está modificando a cadeia de caracteres e, portanto, causar falhas aleatórias. As chamadas para essas funções devem estar sincronizadas.

Requisitos

Rotina	Cabeçalho necessário
_putenv_s	<stdlib.h>
_wputenv_s	<stdlib.h> ou <wchar.h>

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

Exemplo

Para ver uma amostra que mostra como usar _putenv_s, confira getenv_s, _wgetenv_s.

Confira também

Controle de processos e ambientes
getenv, _wgetenv
_searchenv, _wsearchenv