_searchenv_s _wsearchenv_s

Článek
03/26/2013

Při hledání souboru pomocí cesty prostředí.Jedná se o verze _searchenv, _wsearchenv s vylepšení zabezpečení, jak je popsáno v Funkce zabezpečení v CRT.

Důležité
Toto rozhraní API nelze použít v aplikacích, které jsou spuštěny v systému Windows Runtime.Další informace naleznete v tématu CRT funkce nejsou podporovány s /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

Parametry

[v]filename
Název souboru, který chcete vyhledat.
[v]varname
Prostředí pro vyhledávání.
[výstup]pathname
Chcete-li vyrovnávací paměť pro ukládání úplnou cestu.
[v]numberOfElements
Velikost pathname vyrovnávací paměti.

Vrácená hodnota

Nula v případě úspěchu; kód chyby při selhání.

Pokud filename je prázdný řetězec, vrácená hodnota je ENOENT.

Chybové stavy

filename	varname	pathname	numberOfElements	Vrácená hodnota	Obsahpathname
všechny	všechny	NULL	všechny	EINVAL	není k dispozici
NULL	všechny	všechny	všechny	EINVAL	nelze změnit.
všechny	všechny	všechny	< = 0	EINVAL	nelze změnit.

Dojde-li k některé z těchto chybových stavů, je vyvolána obslužná rutina neplatný parametr, jak je popsáno v Ověření parametrů.Pokud je povoleno zpracování, chcete-li pokračovat, tyto funkce set errno na EINVAL a vrátit se EINVAL.

Poznámky

_searchenv_s Obvyklé hledání pro cílový soubor v zadané doméně.varname Proměnná může být jakékoliv prostředí nebo uživatelem definované proměnné, která určuje seznam cest, jako je například PATH, LIB, a INCLUDE.Protože _searchenv_s je malá a velká písmena, varname by měl rozlišovat malá a velká proměnné prostředí.Pokud varname nemá nesouhlasí název proměnné prostředí definované v prostředí v procesu, vrátí funkce hodnotu nula a pathname proměnné se nemění.

Rutinní nejprve hledá soubor v aktuální pracovní adresář.Pokud jej nenalezne, vyhledá další prostřednictvím adresáře určené proměnnou prostředí.Pokud je cílový soubor v některém z těchto adresářů, nově vytvořené cesty je zkopírována do pathname.Pokud filename soubor nebyl nalezen, pathname obsahuje prázdný řetězec zakončený hodnotou null.

pathname Vyrovnávací paměť by měla být nejméně _MAX_PATH znaků dlouhé podle celé délky vypočtené cesta.V opačném případě se _searchenv_s může přetečení pathname za následek neočekávané chování vyrovnávací paměti.

_wsearchenv_sje verzí širokého znaku _searchenv_s; argumenty pro _wsearchenv_s jsou řetězci širokého znaku._wsearchenv_sa _searchenv_s jinak chovat identicky.

V jazyce C++ pomocí těchto funkcí je zjednodušeno díky přetížení šablony; přetížení můžete automaticky odvodit velikost vyrovnávací paměti (není tedy třeba zadat argument velikost) a starší, nezabezpečené funkce lze automaticky nahradí s jejich protějšky novější, bezpečné.Další informace naleznete v tématu Přetížení šablony zabezpečení.

Mapování rutiny obecného textu

Byla zahájena rutina Tchar.h	_UNICODE a _MBCS není definováno	_MBCS, definice	_UNICODE definována
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

Požadavky

Byla zahájena rutina	Požadované záhlaví
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> nebo <wchar.h>

Další informace o kompatibilitě v tématu Compatibility v úvodu.

Příklad

// 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 );
}