_searchenv_s, _wsearchenv_s

Artykuł
03/26/2013

Wyszukiwanie pliku przy użyciu ścieżki środowiska.Są to wersje _searchenv, _wsearchenv z ulepszeń zabezpieczeń, zgodnie z opisem w Funkcje zabezpieczeń w CRT.

Ważne
Ten interfejs API nie można używać w aplikacji, których wykonywanie w czasie wykonywania systemu Windows.Aby uzyskać więcej informacji, zobacz CRT funkcje nie obsł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

[in]filename
Nazwa pliku, aby wyszukać.
[in]varname
Środowisko do wyszukiwania.
[Brak]pathname
Bufor do przechowywania pełną ścieżkę.
[in]numberOfElements
Rozmiar pathname buforu.

Wartość zwracana

Zero, jeśli kończy się pomyślnie; Kod błędu w przypadku awarii.

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

Warunki błędów

filename	varname	pathname	numberOfElements	Zwracana wartość	Zawartośćpathname
wszelkie	wszelkie	NULL	wszelkie	EINVAL	n/d
NULL	wszelkie	wszelkie	wszelkie	EINVAL	nie powinny być zmieniane
wszelkie	wszelkie	wszelkie	< = 0	EINVAL	nie powinny być zmieniane

Jeśli wystąpi którykolwiek z tych warunków błąd, program obsługi nieprawidłowy parametr jest wywoływana, zgodnie z opisem w Sprawdzanie poprawności parametru.Jeśli wykonanie może kontynuować, ustaw te funkcje errno do EINVAL i powrót EINVAL.

Uwagi

_searchenv_s Procedura wyszukiwania dla pliku docelowego w określonej domenie.varname Zmienna może być dowolnym środowisku lub zdefiniowanej zmiennej, która określa listę ścieżek katalogów, takich jak PATH, LIB, i INCLUDE.Ponieważ _searchenv_s jest uwzględniana wielkość liter, varname powinien odpowiadać wielkości zmiennej środowiskowej.Jeśli varname pasuje nie zdefiniowano nazwy zmiennej środowiskowej w środowisku przez proces, funkcja zwraca zero i pathname zmienna nie ulega zmianie.

Rutynowe szuka najpierw plik w bieżącym katalogu roboczym.Jeśli plik nie zostanie znaleziona, wyszukiwanie dalej przez katalogi, określony przez zmienną środowiskową.Jeśli plik docelowy jest w jednym z tych katalogów, nowo utworzona ścieżka jest kopiowana do pathname.Jeśli filename nie zostanie znaleziony plik, pathname zawiera pusty ciąg zakończony znakiem null.

pathname Buforu powinna wynosić co najmniej _MAX_PATH znaków długo, aby pomieściły pełną nazwę ścieżki konstruowanej.W przeciwnym razie _searchenv_s może być przekroczenie pathname buforu spowodowało nieoczekiwane zachowanie.

_wsearchenv_sjest ona szerokich znaków do _searchenv_s; argumenty w funkcji _wsearchenv_s są ciągami szerokich znaków._wsearchenv_si _searchenv_s zachowują się identycznie inaczej.

W języku C++ korzystając z tych funkcji jest uproszczony przez przeciążenia szablonu; przeciążenia mogą wywnioskować długość buforu automatycznie (eliminując konieczność, aby określić argument rozmiar) i starszych, które nie są bezpieczne funkcje mogą automatycznie zastąpić z ich odpowiednikami nowsze, bezpieczne.Aby uzyskać więcej informacji, zobacz Secure, szablon Overloads.

Tekst rodzajowy rutynowych mapowania

Rozpoczęto wykonywanie procedury TCHAR.h	_UNICODE i _MBCS nie zdefiniowany	_MBCS, definicja	_UNICODE, definicja
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

Wymagania

Rozpoczęto wykonywanie procedury	Wymaganego nagłówka
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> lub <wchar.h>

Informacji dotyczących zgodności, zobacz zgodności we wprowadzeniu.

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