_searchenv_s, _wsearchenv_s

Pesquisa por um arquivo usando caminhos de ambiente. Essas versões do , _wsearchenvtêm aprimoramentos de_searchenv segurança, conforme descrito em Recursos de segurança no CRT.

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

filename
O nome de arquivo a ser pesquisado.

varname
O ambiente a pesquisar.

pathname
O buffer para armazenar o caminho completo.

numberOfElements
Tamanho do pathname buffer.

Valor retornado

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

Se filename for uma cadeia de caracteres vazia, o valor retornado será ENOENT.

Condições de erro

filename	varname	pathname	numberOfElements	Valor retornado	Conteúdo de pathname
any	qualquer	NULL	any	EINVAL	N/D
NULL	any	qualquer	any	EINVAL	não alterado
any	qualquer	any	<= 0	EINVAL	não alterado

Se qualquer uma dessas condições de erro ocorrer, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, essas funções definirão errno como EINVAL e retornarão EINVAL.

Comentários

A rotina _searchenv_s pesquisará pelo arquivo de destino no domínio especificado. A variável varname pode ser qualquer ambiente ou variável definida pelo usuário que especifica uma lista de caminhos de diretório, por exemplo, PATH, LIB e INCLUDE. Já que _searchenv_s diferencia maiúsculas de minúsculas, o uso de maiúsculas e minúsculas em varname deve corresponder àquele encontrado na variável de ambiente. Se varname não corresponder ao nome de uma variável de ambiente definida no ambiente do processo, a função retornará zero e a pathname variável não será alterada.

A rotina pesquisa pelo arquivo primeiramente no diretório de trabalho atual. Se não encontrar o arquivo, ele procurará em seguida os diretórios especificados pela variável de ambiente. Se o arquivo de destino estiver em um desses diretórios, o caminho criado recentemente será copiado para pathname. Se o filename arquivo não for encontrado, pathname conterá uma cadeia de caracteres vazia terminada em nulo.

O buffer pathname deve ter pelo menos _MAX_PATH caracteres para acomodar o comprimento total do nome do caminho criado. Caso contrário, _searchenv_s poderia causar um estouro de buffer pathname, resultando em um comportamento inesperado.

_wsearchenv_s é uma versão de caractere largo de _searchenv_s; os argumentos para _wsearchenv_s são cadeias de caracteres largas. Caso contrário, _wsearchenv_s e _searchenv_s se comportam de forma idêntica.

Em C++, o uso dessas funções é simplificado pelas sobrecargas de modelo; as sobrecargas podem inferir o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras por suas equivalentes mais recentes e seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.

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

Rotina Tchar.h	_UNICODE e _MBCS não definidos	_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 informações sobre compatibilidade, consulte Compatibilidade.

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 2010\VC\BIN\CL.EXE

Confira também

Controle de diretório
_searchenv, _wsearchenv
getenv, _wgetenv
_putenv, _wputenv