_searchenv, _wsearchenv

Usa caminhos de ambiente para pesquisar por um arquivo. Versões mais seguras dessas funções estão disponíveis; consulte _searchenv_s, _wsearchenv_s.

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

void _searchenv(
   const char *filename,
   const char *varname,
   char *pathname
);
void _wsearchenv(
   const wchar_t *filename,
   const wchar_t *varname,
   wchar_t *pathname
);
template <size_t size>
void _searchenv(
   const char *filename,
   const char *varname,
   char (&pathname)[size]
); // C++ only
template <size_t size>
void _wsearchenv(
   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.

nome
O buffer para armazenar o caminho completo.

Comentários

A rotina _searchenv procura o arquivo de destino no domínio especificado. A variável VarName pode ser qualquer ambiente ou variável definida pelo usuário — por exemplo, Path, libou include— que especifica uma lista de caminhos de diretório. Como _searchenv diferencia maiúsculas de minúsculas, VarName deve corresponder ao caso da variável de ambiente.

A rotina pesquisa pelo arquivo primeiramente no diretório de trabalho atual. Se não encontrar o arquivo, ela procurará nos diretórios especificados pela variável de ambiente. Se o arquivo de destino estiver em um desses diretórios, o caminho recém-criado será copiado em PathName. Se o arquivo filename não for encontrado, PathName conterá uma cadeia de caracteres vazia terminada em nulo.

O buffer de nome de caminho deve ter pelo menos _MAX_PATH caracteres para acomodar o comprimento completo do nome de caminho construído. Caso contrário, _searchenv pode saturar o buffer de nome de caminho e causar um comportamento inesperado.

_wsearchenv é uma versão de caractere largo do _searchenve os argumentos para _wsearchenv são cadeias de caracteres largos. _wsearchenv e _searchenv se comportar de forma idêntica.

Se filename for uma cadeia de caracteres vazia, essas funções retornarão ENOENT.

Se filename ou PathName for um ponteiro NULL , 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 retornam-1 e definem errno como EINVAL.

Para obter mais informações sobre códigos de erro e errno , consulte constantes errno.

Em C++, essas funções têm sobrecargas de modelo que invocam os equivalentes mais recentes e mais seguros dessas funções. Para obter mais informações, consulte Sobrecargas de modelo seguro.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar isso, consulte estado global no CRT.

Mapeamentos da rotina de texto genérico

Rotina Tchar.h _UNICODE e _MBCS não definidos _MBCS definido _UNICODE definido
_tsearchenv _searchenv _searchenv _wsearchenv

Requisitos

Rotina Cabeçalho necessário
_searchenv <stdlib.h>
_wsearchenv <stdlib. h > ou < WCHAR. h>

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

Exemplo

// crt_searchenv.c
// compile with: /W3
// This program searches for a file in
// a directory that's 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";

   // Search for file in PATH environment variable:
   _searchenv( searchfile, envvar, pathbuffer ); // C4996
   // Note: _searchenv is deprecated; consider using _searchenv_s
   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 8\VC\BIN\CL.EXE

Confira também

Controle de diretório
getenv, _wgetenv
_putenv, _wputenv
_searchenv_s, _wsearchenv_s