_searchenv_s, _wsearchenv_s

Artigo
08/25/2010

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

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.
[in]varname
Ambiente de Pesquisar.
[out] pathname
Buffer para armazenar o caminho completo.
[in]numberOfElements
Size of the pathnamebuffer.

Valor de retorno

Zero se for bem-sucedida; um código de erro em caso de falha.

If filename é uma seqüência vazia, o valor retornado é ENOENT.

Condições de erro

filename	varname	pathname	numberOfElements	Valor de Retorno	Sumário de pathname
any	any	NULL	any	EINVAL	n/d
NULL	any	any	any	EINVAL	não alterado
any	any	any	<= 0	EINVAL	não alterado

Se qualquer uma dessas condições de erro ocorrer, o manipulador de parâmetro inválido é chamado, conforme descrito em Validação de parâmetro. Se a execução for permitida para continuar, essas funções conjunto errno para EINVAL e retornar EINVAL.

Comentários

The _searchenv_s pesquisas de rotina para o arquivo de destino no domínio especificado. The varname variável pode ser qualquer ambiente ou variável definida pelo usuário que especifica uma lista de caminhos de diretório, tal sistema autônomo PATH, LIB, e INCLUDE. Porque _searchenv_s diferenciar diferenciar maiúsculas de minúsculas, varname deve corresponder ao caso da variável de ambiente. If varname faz a correspondência não o nome de uma variável de ambiente definido no ambiente do processo, a função retorna zero e o pathname variável não é alterada.

A rotina procura primeiro o arquivo no diretório de trabalho corrente.Se ele não localizar o arquivo, procura próxima por meio de diretórios especificados pela variável de ambiente.Se o arquivo de destino estiver em um desses diretórios, o caminho recém-criado é copiado para pathname. Se o filename arquivo não for encontrado, pathname contém uma seqüência de caracteres vazia terminada com caractere nulo.

The pathname buffer deve ser pelo menos _MAX_PATH caracteres de comprimento para acomodar o completo comprimento do nome do caminho construído. Caso contrário, _searchenv_s saturação pode ser o pathname buffer resultando em um comportamento inesperado.

_wsearchenv_sé uma versão de caractere largo da _searchenv_s; os argumentos para _wsearchenv_ssão seqüências de caracteres largos. _wsearchenv_s e _searchenv_s tenham comportamento idêntico caso contrário.

No C++, usando essas funções é simplificado pelo modelo sobrecargas; sobrecargas de podem inferir o comprimento do buffer automaticamente (eliminando a necessidade de especificar um argumento de dimensionar) e eles podem substituir automaticamente funções não seguras, mais antigas, com suas contrapartes mais recentes e seguras.For more information, see Proteger overloads de modelo.

Mapeamentos de rotina de texto genérica

Rotina tchar.h	_UNICODE e _MBCS não definido	_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 obter mais informações de compatibilidade, consulte 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 );
}

Path for CL.EXE: C:\Program Files\Microsoft Visual Studio 2005\VC7\BIN\CL.EXE