_searchenv, _wsearchenv

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

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.

pathname
O buffer para armazenar o caminho completo.

Comentários

A rotina _searchenv pesquisará pelo 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, LIB e INCLUDE – que especifica uma lista de caminhos de diretório. Já que _searchenv 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.

A rotina pesquisa pelo arquivo primeiramente no diretório de trabalho atual. Se ele não encontrar o arquivo, ele examinará 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 poderia causar um estouro de buffer pathname e causar um comportamento inesperado.

_wsearchenv é uma versão de caractere largo de _searchenv e os argumentos para _wsearchenv são cadeias de caracteres largos. Caso contrário, _wsearchenv e _searchenv se comportam de forma idêntica.

Se filename é uma cadeia de caracteres vazia, essas funções retornam ENOENT.

Se filename or pathname for um NULL ponteiro, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, essas funções retornarão -1 e definirão errno como EINVAL.

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

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