_searchenv_s, _wsearchenv_s

Wyszukuje plik przy użyciu ścieżek środowiskowych. Te wersje programu _searchenv_wsearchenvmają ulepszenia zabezpieczeń zgodnie z opisem w temacie Funkcje zabezpieczeń w narzędziu CRT.

Ważne

Tego interfejsu API nie można używać w aplikacjach wykonywanych w środowisko wykonawcze systemu Windows. Aby uzyskać więcej informacji, zobacz Funkcje CRT nieobsługiwane w aplikacjach platforma uniwersalna systemu Windows.

Składnia

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
Nazwa pliku do wyszukania.

varname
Środowisko do wyszukiwania.

pathname
Bufor do przechowywania pełnej ścieżki.

numberOfElements
Rozmiar buforu pathname .

Wartość zwracana

Zero w przypadku powodzenia; kod błędu dotyczący błędu.

Jeśli filename jest pustym ciągiem, zwracana wartość to ENOENT.

Warunki błędu

filename	varname	pathname	numberOfElements	Wartość zwracana	Zawartość pathname
dowolny	dowolny	NULL	dowolny	EINVAL	nie dotyczy
NULL	dowolny	dowolny	dowolny	EINVAL	nie zmieniono
dowolny	dowolny	dowolny	<= 0	EINVAL	nie zmieniono

Jeśli wystąpi którykolwiek z tych warunków błędu, wywoływana jest nieprawidłowa procedura obsługi parametrów, zgodnie z opisem w temacie Weryfikacja parametrów. Jeśli wykonywanie jest dozwolone do kontynuowania, te funkcje są ustawione errno na EINVAL i zwracają wartość EINVAL.

Uwagi

Rutynowe _searchenv_s wyszukiwanie pliku docelowego w określonej domenie. Zmienna varname może być dowolną zmienną środowiskową lub zdefiniowaną przez użytkownika, która określa listę ścieżek katalogu, takich jak PATH, LIBi INCLUDE. Ponieważ _searchenv_s uwzględniana jest wielkość liter, varname powinna odpowiadać wielkości liter zmiennej środowiskowej. Jeśli varname zmienna środowiskowa zdefiniowana w środowisku procesu nie jest zgodna z nazwą zmiennej środowiskowej, funkcja zwraca zero, a zmienna pathname pozostaje niezmieniona.

Rutynowe wyszukiwanie najpierw pliku w bieżącym katalogu roboczym. Jeśli plik nie zostanie odnaleźć, będzie on wyglądać dalej za pośrednictwem katalogów określonych przez zmienną środowiskową. Jeśli plik docelowy znajduje się w jednym z tych katalogów, nowo utworzona ścieżka zostanie skopiowana do pathnamepliku . filename Jeśli plik nie zostanie znaleziony, pathname zawiera pusty ciąg zakończony wartością null.

Bufor pathname powinien mieć długość co najmniej _MAX_PATH znaków, aby pomieścić pełną długość skonstruowanej nazwy ścieżki. _searchenv_s W przeciwnym razie może zostać zastąpiony pathname bufor, co spowoduje nieoczekiwane zachowanie.

_wsearchenv_s jest wersją szerokoznakową ; _searchenv_sargumenty, które mają _wsearchenv_s być ciągami o szerokim znaku. _wsearchenv_s i _searchenv_s zachowywać się identycznie inaczej.

W języku C++używanie tych funkcji jest uproszczone przez przeciążenia szablonu; przeciążenia mogą automatycznie wnioskować długość buforu (eliminując konieczność określenia argumentu rozmiaru) i mogą automatycznie zastępować starsze, niezabezpieczone funkcje nowszymi, bezpiecznymi odpowiednikami. Aby uzyskać więcej informacji, zobacz Bezpieczne przeciążenia szablonów.

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Mapowania procedur tekstu ogólnego

Procedura tchar.h	_UNICODE i _MBCS niezdefiniowane	_MBCS Zdefiniowane	_UNICODE Zdefiniowane
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

Wymagania

Procedura	Wymagany nagłówek
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> lub <wchar.h>

Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.

Przykład

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

Zobacz też

Kontrolka katalogu
_searchenv, _wsearchenv
getenv, _wgetenv
_putenv, _wputenv