_searchenv_s, _wsearchenv_s

Vyhledá soubor pomocí cest prostředí. Tyto verze _searchenvmají _wsearchenv vylepšení zabezpečení, jak je popsáno v funkcích zabezpečení v CRT.

Důležité

Toto rozhraní API nelze použít v aplikacích, které se spouští v prostředí Windows Runtime. Další informace najdete v tématu Funkce CRT, které nejsou v aplikacích Univerzální platforma Windows podporované.

Syntaxe

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

filename
Název souboru, který chcete vyhledat.

varname
Prostředí, které se má hledat.

pathname
Vyrovnávací paměť pro uložení úplné cesty.

numberOfElements
pathname Velikost 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, návratová hodnota je ENOENT.

Chybové podmínky

filename	varname	pathname	numberOfElements	Vrácená hodnota	Obsah pathname
jakékoliv	jakékoliv	NULL	jakékoliv	EINVAL	Není k dispozici
NULL	jakékoliv	jakékoliv	jakékoliv	EINVAL	nezměnilo se
jakékoliv	jakékoliv	jakékoliv	<= 0	EINVAL	nezměnilo se

Pokud dojde k některé z těchto chybových podmínek, vyvolá se neplatná obslužná rutina parametru, jak je popsáno v ověření parametru. Pokud provádění může pokračovat, tyto funkce jsou nastaveny errno na EINVAL a vracet EINVAL.

Poznámky

Rutina _searchenv_s vyhledá cílový soubor v zadané doméně. Proměnnou varname může být libovolné prostředí nebo uživatelsky definovaná proměnná, která určuje seznam cest adresářů, například PATH, LIBa INCLUDE. Vzhledem k tomu _searchenv_s , že se rozlišují malá a velká písmena, varname by se měla shodovat s případem proměnné prostředí. Pokud varname neodpovídá názvu proměnné prostředí definované v prostředí procesu, vrátí funkce nulu a pathname proměnná se nezmění.

Rutina nejprve vyhledá soubor v aktuálním pracovním adresáři. Pokud soubor nenajde, bude vypadat dál prostřednictvím adresářů určených proměnnou prostředí. Pokud je cílový soubor v jednom z těchto adresářů, nově vytvořená cesta se zkopíruje do pathname. filename Pokud se soubor nenajde, pathname obsahuje prázdný řetězec ukončený hodnotou null.

Vyrovnávací pathname paměť by měla mít délku alespoň _MAX_PATH znaků, aby vyhovovala celé délce názvu vytvořené cesty. Jinak může dojít k pathname přetečení vyrovnávací paměti, _searchenv_s což vede k neočekávanému chování.

_wsearchenv_s je verze širokého znaku _searchenv_s; argumenty, které mají _wsearchenv_s být řetězce širokého znaku. _wsearchenv_s a _searchenv_s chovat se stejně jinak.

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

Ve výchozím nastavení je globální stav této funkce vymezen na aplikaci. Chcete-li toto chování změnit, přečtěte si téma Globální stav v CRT.

Mapování rutin obecného textu

Rutina Tchar.h	_UNICODE a _MBCS není definován	_MBCS definovaný	_UNICODE definovaný
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

Požadavky

Rutina	Požadovaný hlavičkový soubor
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> nebo <wchar.h>

Další informace o kompatibilitě najdete 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 );
}

Path for CL.EXE:
C:\Program Files\Microsoft Visual Studio 2010\VC\BIN\CL.EXE

Viz také

Ovládací prvek adresář
_searchenv, _wsearchenv
getenv, _wgetenv
_putenv, _wputenv