_searchenv_s, _wsearchenv_s

Artigo
03/12/2013

Procura um arquivo usando caminhos de ambiente.Essas são versões de _searchenv, _wsearchenv com aprimoramentos de segurança conforme descrito em Recursos de segurança no CRT.

Importante
Este API não pode ser usado em aplicativos executados em Tempo de Execução do Windows.Para obter mais informações, consulte Funções de CRT não suportadas com /ZW.

errno_t _searchenv_s( const char *filename, const char *varname, char *pathname, size_t numberOfElements ); errno_t _wsearchenv_s( const wchar_t *filename, const wchar_t *varname, wchar_t *pathname, size_t numberOfElements ); template <size_t size> errno_t _searchenv_s( const char *filename, const char *varname, char (&pathname)[size] ); // C++ only template <size_t size> errno_t _wsearchenv_s( const wchar_t *filename, const wchar_t *varname, wchar_t (&pathname)[size] ); // C++ only

Parâmetros

[in] filename
Nome do arquivo para procurar por.
[in] varname
Ambiente a pesquisa.
[out] pathname
Buffer para armazenar o caminho completo.
[in] numberOfElements
Tamanho do buffer pathname.

Valor de retorno

Zero se com êxito; um código de erro em caso de falha.

Se filename é uma cadeia de caracteres vazia, o valor de retorno é ENOENT.

Condições de erro

filename	varname	pathname	numberOfElements	Valor de Retorno	Conteúdo de pathname
alguns	alguns	NULL	alguns	EINVAL	n/d
NULL	alguns	alguns	alguns	EINVAL	não modificado
alguns	alguns	alguns	<= 0	EINVAL	não modificado

Se qualquer uma dessas condições de erro ocorre, o manipulador inválido do parâmetro é invocado, como descrito em Validação de parâmetro.Se a execução é permitida continuar, este errno definir funções a EINVAL e a EINVALde retorno.

Comentários

Pesquisas rotineiras de _searchenv_s para o arquivo de destino no domínio especificado.A variável de varname pode ser qualquer variável ou ambiente definido pelo usuário que especifica uma lista de caminhos de diretório, como PATH, LIB, e INCLUDE.Porque _searchenv_s diferencia maiúsculas de minúsculas, varname deve coincidir com os exemplos da variável de ambiente.Se varname não corresponde ao nome de uma variável de ambiente definido no ambiente de processo, a função retorna zero e a variável de pathname é inalterado.

A rotina primeiro procura por arquivo no diretório de trabalho corrente.Se não encontra o arquivo parece em seguida, através de pastas especificados pela variável de ambiente.Se o arquivo de destino está em um desses diretórios, o caminho recém-criado é copiado para pathname.Se o arquivo de filename não for encontrado, pathname contém uma cadeia de caracteres vazia NULL- finalizada.

O buffer de pathname deve ser pelo menos caracteres de _MAX_PATH long para acomodar o comprimento total do nome do caminho construído.Caso contrário, _searchenv_s pode passar o buffer de pathname resultando em um comportamento inesperado.

_wsearchenv_s é uma versão de largo- caractere de _searchenv_s; os argumentos para _wsearchenv_s são cadeias de caracteres de largo- caractere._wsearchenv_s e _searchenv_s se comportam de forma idêntica.

Em C++, usar essas funções é simplificada por sobrecargas de modelo; as sobrecargas podem interpretar o tamanho do buffer (automaticamente que elimina a necessidade de especificar um argumento de tamanho) e podem automaticamente substituir mais antigos, não funções de segurança mais recentes, com suas contrapartes seguros.Para obter mais informações, consulte Proteger Overloads de modelo.

Mapeamentos da rotina de Genérico- texto

Rotina de Tchar.h	_UNICODE e não definidos _MBCS	_MBCS definido	_UNICODE definido
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

Requisitos

Rotina	Cabeçalho necessário
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> ou <wchar.h>

Para mais informações, consulte Compatibilidade de compatibilidade na introdução.

Exemplo

// crt_searchenv_s.c
/* This program searches for a file in
 * a directory specified by an environment variable.
 */

#include <stdlib.h>
#include <stdio.h>

int main( void )
{
   char pathbuffer[_MAX_PATH];
   char searchfile[] = "CL.EXE";
   char envvar[] = "PATH";
   errno_t err;

   /* Search for file in PATH environment variable: */
   err = _searchenv_s( searchfile, envvar, pathbuffer, _MAX_PATH );
   if (err != 0)
   {
      printf("Error searching the path. Error code: %d\n", err);
   }
   if( *pathbuffer != '\0' )
      printf( "Path for %s:\n%s\n", searchfile, pathbuffer );
   else
      printf( "%s not found\n", searchfile );
}