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

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.

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

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