_searchenv_s, _wsearchenv_s

Artykuł
06/09/2015

Wyszukiwanie plików przy użyciu ścieżki środowiska.Te wersje _searchenv, _wsearchenv mają wzmocnienia zabezpieczeń, jak opisano w Funkcje zabezpieczeń w CRT.

Ważne
Tego API nie można używać w aplikacjach korzystających ze środowiska wykonawczego Windows.Aby uzyskać więcej informacji, zobacz Funkcje CRT nieobsługiwane przez /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

[w] filename
Nazwa pliku do wyszukania.
[in] varname
Środowisko do wyszukiwania.
[poza] pathname
Bufor do przechowywania pełnej ścieżki.
[w] numberOfElements
Rozmiar pathnamebuforu.

Wartość zwracana

Zero, jeśli operacja się powiedzie; w przeciwnym razie, kod błędu.

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

Warunki błędów

filename	varname	pathname	numberOfElements	Wartość zwrócona	Zawartośćpathname
jakakolwiek	jakakolwiek	NULL	jakakolwiek	EINVAL	Nie dotyczy
NULL	jakakolwiek	jakakolwiek	jakakolwiek	EINVAL	nie zmienione
jakakolwiek	jakakolwiek	jakakolwiek	<= 0	EINVAL	nie zmienione

Jeśli występuje którykolwiek z tych warunków błędu, procedura obsługi nieprawidłowego parametru jest wywoływana, zgodnie z opisem w Sprawdzanie poprawności parametru.Jeśli wykonanie może być kontynuowane, te funkcje ustawiają errno jako EINVAL i zwracają EINVAL.

Uwagi

_searchenv_s procedura wyszukiwania pliku docelowego w określonej domenie.varname zmienna może być dowolnym środowiskiem lub zmienną zdefiniowaną przez użytkownika, który określa listę ścieżek katalogów, takich jak PATH, LIB, i INCLUDE.Ponieważ _searchenv_s uwzględnia wielkość liter, varname powinien odpowiadać wielkości zmiennej środowiskowej.Jeśli varname nie pasuje do nazwy zmiennej środowiskowej zdefiniowanej w środowisku procesu, funkcja zwraca zero i zmienna pathname nie ulega zmianie.

Rutyna szuka najpierw pliku w bieżącym katalogiem roboczym.Jeśli nie odnajdzie pliku, szuka dalej przez katalogi określone przez zmienną środowiskową.Jeśli plik docelowy znajduje się w jednym z tych katalogów, nowo utworzona ścieżka jest kopiowana do pathname.Jeśli nie znaleziono pliku filename, pathname zawiera pusty ciąg zakończony znakiem null.

pathname buforu powinien wynosić co najmniej _MAX_PATH znaków, aby można było pomieścić taką pełną nazwę ścieżki konstruowanej.W przeciwnym razie _searchenv_s przekroczenie pathname buforu mogło spowodować nieoczekiwane zachowanie.

_wsearchenv_s to wersja znaku dwubajtowego _searchenv_s; argumenty do _wsearchenv_s to ciągi znaku dwubajtowego._wsearchenv_s i _searchenv_s zachowują się identycznie w innych przypadkach.

W języku programowania C++ korzystanie z tych funkcji jest uproszczone przez przeciążania szablonu; przeciążania mogą automatycznie wywnioskować długość buforu (tak, aby nie było konieczne określenie argumentu rozmiaru), ponadto te funkcje mogą automatycznie zastąpić starsze, niezabezpieczone funkcje nowszymi, bardziej bezpiecznymi odpowiednikami.Aby uzyskać więcej informacji, zobacz Przeciążenia bezpiecznych szablonów.

Rutynowe mapowania zwykłego tekstu

Procedura Tchar.h	_UNICODE i _MBCS nie zdefiniowany	_MBCS zdefiniowano	_UNICODE zdefiniowany
_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 na temat 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 );
}