_searchenv_s, _wsearchenv_s

Článek
06/09/2015

Vyhledá soubor pomocí cest prostředí.Tyto verze _searchenv, _wsearchenv mají zlepšené zabezpečení popsané v tématu Funkce zabezpečení v CRT.

Důležité
Toto API nelze použít v aplikacích, které jsou spuštěny v modulu 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

[in] filename
Název souboru, který chcete vyhledat.
[in] varname
Prostředí pro vyhledávání.
[out] pathname
Vyrovnávací paměť pro ukládání úplné cesty.
[in] numberOfElements
Velikost vyrovnávací paměti pathname.

Vrácená hodnota

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

Pokud je filename prázdný řetězec, návratová hodnota je ENOENT.

Chybové podmínky

filename	varname	pathname	numberOfElements	Návratová hodnota	Obsah pathname
any	any	NULL	any	EINVAL	není k dispozici
NULL	any	any	any	EINVAL	beze změny
any	any	any	<= 0	EINVAL	beze změny

Pokud dojde k některému z těchto chybových stavů, je vyvolán neplatný parametr obslužné rutiny, jak je popsáno v Ověření parametru.Pokud smí provádění pokračovat, tyto funkce nastaví errno na EINVAL a vrátí EINVAL.

Poznámky

Rutina _searchenv_s vyhledává cílový soubor v zadané doméně.Proměnná varname může být jakákoli proměnná prostředí nebo uživatelem definovaná, která určuje seznam cest adresáře, jako je například PATH, LIB nebo INCLUDE.Protože _searchenv_s rozlišuje velká a malá písmena, varname by měl odpovídat proměnné prostředí.Pokud varname neodpovídá názvu proměnné prostředí definované v prostředí procesu, vrátí funkce hodnotu nula a proměnná pathname je beze změny.

Rutina nejprve hledá soubor v aktuálním pracovním adresáři.Pokud soubor nelze najít, hledá dále v adresářích určených proměnnou prostředí.Je-li cílový soubor v některém z těchto adresářů, nově vytvořená cesta je zkopírována do pathname.Pokud soubor filename nebyl nalezen, pathname obsahuje prázdný řetězec zakončený hodnotou null.

Vyrovnávací paměť pathname musí být alespoň _MAX_PATH znaků dlouhá, aby se do ní vešel úplný název vytvořené cesty.Jinak _searchenv_s může způsobit přetečení vyrovnávací paměti pathname, což bude mít za následek neočekávané chování.

_wsearchenv_s je širokoznaká verze _searchenv_s. Argumenty pro _wsearchenv_s jsou širokoznaké řetězce._wsearchenv_s a _searchenv_s se jinak chovají stejně.

V jazyce C++ je použití těchto funkcí zjednodušeno díky přetížení šablon; přetížení dokáží odvodit velikost vyrovnávací paměti automaticky (tak, že eliminují potřebu zadat argument velikosti) a automaticky nahradit starší, nezabezpečené funkce jejími novějšími, bezpečnějšími protějšky.Další informace naleznete v tématu Přetížení zabezpečení šablony.

Rutinní mapování obecného textu

Rutina Tchar.h	_UNICODE a _MBCS nejsou definovány	_MBCS definováno	_UNICODE definováno
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

Požadavky

Rutina	Požadované záhlaví
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> nebo <wchar.h>

Další informace o kompatibilitě naleznete v tématu Kompatibilita.

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