_searchenv_s, _wsearchenv_s

Artigo
06/09/2015

Procura um arquivo usando caminhos do ambiente. Essas versões de _searchenv, _wsearchenv têm aprimoramentos de segurança, como descrito em Recursos de segurança no CRT.

Importante

Esta API não pode ser usada em aplicativos que executam no Tempo de Execução do Windows.Para obter mais informações, consulte Funções CRT sem suporte pelo /ZW.

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

[entrada] filename
Nome do arquivo a ser pesquisado.
[entrada] varname
Ambiente a ser pesquisado.
[saída] pathname
Buffer para armazenar o caminho completo.
[entrada] numberOfElements
O tamanho do buffer pathname.

Valor de retorno

Zero se tiver êxito; um código de erro em falha.

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

Condições de erro

filename	varname	pathname	numberOfElements	Valor de retorno	Conteúdo de pathname
any	any	NULL	any	EINVAL	n/d
NULL	any	any	any	EINVAL	não alterado
any	any	any	<= 0	EINVAL	não alterado

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

Comentários

A rotina _searchenv_s pesquisa o 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, como PATH, LIB e INCLUDE. Como _searchenv_s diferencia maiúsculas de minúsculas, varname deve corresponder ao caso de 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 retorna zero e a variável de pathname é inalterada.

A rotina procura primeiro o arquivo no diretório de trabalho atual. Se ele não encontrar o arquivo, ele 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 é copiado para pathname. Se o arquivo de filename não for encontrado, pathname contém uma cadeia de caracteres vazia terminada em nulo.

O buffer pathname deve ter pelo menos _MAX_PATH caracteres para acomodar o tamanho total do nome de caminho construído. Do contrário, _searchenv_s pode ocasionar um estouro do 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 caractere amplo. Caso contrário, _wsearchenv_s e _searchenv_s, ao contrário, se comportam de forma idêntica.

No C++, o uso dessas funções é simplificado por sobrecargas de modelo; as sobrecargas podem interpretar o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente as funções menos seguras mais antigas por correspondentes mais seguras e mais recentes. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Mapeamentos da 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 mais 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 );
}