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

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

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

Requisitos

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