_putenv_s, _wputenv_s

Artigo
06/09/2015

Cria, modifica ou remove variáveis de ambiente. Essas são versões de _putenv, _wputenv mas tem aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

Importante

Não é possível usar essa API em aplicativos executados no Tempo de Execução do Windows.Para obter mais informações, consulte Funções CRT sem suporte pelo /ZW.

errno_t _putenv_s(
   const char *name,
   const char *value 
);
errno_t _wputenv_s(
   const wchar_t *name,
   const wchar_t *value
);

Parâmetros

name
O nome da variável de ambiente.
value
O valor para definir a variável de ambiente a.

Valor de retorno

Retornará 0 se tiver êxito, ou um código de erro.

Condições de erro

name	value	Valor de retorno
NULL	any	EINVAL
any	NULL	EINVAL

Se uma das condições de erro ocorrer, essas funções invoca um manipulador inválido do parâmetro, conforme descrito em Validação do 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. As variáveis de ambiente definem o ambiente em que um processo é executado (por exemplo, o caminho de pesquisa padrão para que as bibliotecas sejam vinculadas com um programa). _wputenv_s é uma versão de caractere longo de _putenv_s; o argumento envstring para _wputenv_s é uma cadeia de caractere longo.

Mapeamentos da rotina de texto genérico

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_MBCS definido	_UNICODE definido
_tputenv_s	_putenv_s	_putenv_s	_wputenv_s

name é o nome da variável de ambiente a ser adicionado ou alterado e value é o valor da variável. Se name faz mais parte do ambiente, seu valor é substituído por value; caso contrário, o novo variável de name e seu value são adicionados ao ambiente. Você pode remover uma variável de ambiente especificando uma cadeia de caracteres vazia ("") ou seja, para value.

_putenv_s e _wputenv_s afetam somente o ambiente do local para o processo atual; não é possível usá-los para modificar o ambiente no nível de comando. Essas funções funcionam apenas nas estruturas de dados que são acessíveis à biblioteca de tempo de execução e não no ambiente “bucket” que o sistema operacional para criar um processo. Quando o processo atual terminar, o ambiente reverte ao nível do processo de chamada, que está na maioria dos casos o nível do sistema operacional. Porém, o ambiente alterado pode ser passado a todos os novos processos que são criados por _spawn, por _exec, ou por system, e esses novos processos obter quaisquer novos itens que são adicionados por _putenv_s e por _wputenv_s.

Não altere uma entrada de ambiente diretamente; em vez disso, use _putenv_s ou _wputenv_s para alterá-lo. Em particular, diretamente liberar os elementos da matriz global de _environ[] pode provocar a memória inválido a ser tratada.

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 de _wenviron, e invalidam assim o argumento de envp a main e o argumento de _wenvp a wmain. Portanto, é mais seguro usar _environ ou _wenviron para acessar informações de ambiente. Para obter mais informações sobre a relação de _putenv_s e de _wputenv_s a variáveis globais, consulte _environ, _wenviron.

Dica

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 quando _putenv_s alterar a cadeia de caracteres, e assim aleatórias causa de falhas.Certifique-se de que as chamadas para essas funções sejam sincronizadas.

Requisitos

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

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

Exemplo

Para obter um exemplo que mostra como usar _putenv_s, consulte getenv_s, _wgetenv_s.

Equivalência do .NET Framework

Não aplicável. Para chamar a função padrão de C, use PInvoke. Para obter mais informações, consulte Exemplos de invocação de plataforma.

Consulte também

Referência

Processo e controle de ambiente

getenv, _wgetenv

_searchenv, _wsearchenv

Compartilhar via