_searchenv_s, _wsearchenv_s

Sucht mithilfe von Umgebungspfaden nach einer Datei. Diese Versionen von _searchenv, _wsearchenv verfügen über Sicherheitsverbesserungen, wie in sicherheitsfeatures im CRT beschrieben.

Wichtig

Diese API kann nicht in Anwendungen verwendet werden, die in Windows-Runtime ausgeführt werden. Weitere Informationen finden Sie im Artikel CRT functions not supported in Universal Windows Platform apps (In Apps für die universelle Windows-Plattform nicht unterstützte CRT-Funktionen).

Syntax

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

Parameter

filename
Der Name der zu suchenden Datei.

varname
Zu durchsuchende Umgebung.

pathname
Puffer zum Speichern des vollständigen Pfades.

numberOfElements
Größe des Puffers pathname .

Rückgabewert

Null, wenn erfolgreich, ein Fehlercode, wenn ein Fehler auftritt.

Wenn filename eine leere Zeichenfolge ist, dann ist der Rückgabewert ENOENT.

Fehlerbedingungen

filename	varname	pathname	numberOfElements	Rückgabewert	Inhalt von pathname
any	Beliebig	NULL	any	EINVAL	Nicht zutreffend
NULL	any	Beliebig	any	EINVAL	nicht geändert
any	Beliebig	any	<= 0	EINVAL	nicht geändert

Wenn eine dieser Fehlerbedingungen auftritt, wird der ungültige Parameterhandler aufgerufen, wie in der Parameterüberprüfung beschrieben. Wenn die weitere Ausführung zugelassen wird, stellen diese Funktionen errno auf EINVAL ein und geben EINVAL zurück.

Hinweise

Die _searchenv_s-Routine sucht in der angegebenen Domäne nach der Zieldatei. Die varname-Variable kann jede beliebige Umgebungsvariable oder benutzerdefinierte Variable sein, die eine Liste von Verzeichnispfaden angibt, wie z. B. PATH, LIB und INCLUDE. Da _searchenv_s die Groß-/Kleinschreibung beachtet, sollte varname mit der Groß-/Kleinschreibung der Umgebungsvariablen übereinstimmen. Wenn varname der Name einer Umgebungsvariable, die in der Umgebung des Prozesses definiert ist, nicht übereinstimmt, gibt die Funktion Null zurück, und die pathname Variable ist unverändert.

Die Routine sucht zuerst im aktuellen Arbeitsverzeichnis nach der Datei. Wenn die Datei nicht gefunden wird, werden die verzeichnisse, die durch die Umgebungsvariable angegeben sind, weiter durchschaut. Wenn die Zieldatei in einem dieser Verzeichnisse ist, wird der neu erstellte Pfad in pathname kopiert. Wenn die filename Datei nicht gefunden wird, pathname enthält eine leere null-beendete Zeichenfolge.

Der Puffer pathname sollte mindestens _MAX_PATH Zeichen lang sein, um die volle Länge des erstellten Pfadnamens zu unterstützen. Andernfalls kann _searchenv_s den pathname-Puffer überlaufen lassen, was zu einem unerwarteten Verhalten führt.

_wsearchenv_s ist eine Breitzeichenversion von _searchenv_s. Die Argumente für _wsearchenv_s sind Zeichenfolgen mit Breitzeichen. _wsearchenv_s und _searchenv_s verhalten sich andernfalls identisch.

In C++ wird die Verwendung dieser Funktionen durch Vorlagenüberladungen vereinfacht; die Überladungen können automatisch Rückschlüsse auf die Pufferlänge ziehen (wodurch kein Größenargument mehr angegeben werden muss), und sie können automatisch die älteren, nicht sicheren Funktionen durch ihre neueren, sicheren Entsprechungen ersetzen. Weitere Informationen finden Sie unter Secure Template Overloads.

Standardmäßig gilt der globale Zustand dieser Funktion für die Anwendung. Wie Sie dieses Verhalten ändern, erfahren Sie unter Globaler Status in der CRT.

Mapping generischer Textroutinen

Tchar.h-Routine	_UNICODE und _MBCS nicht definiert	_MBCS definiert	_UNICODE definiert
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

Anforderungen

Routine	Erforderlicher Header
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> oder <wchar.h>

Weitere Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Beispiel

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

Siehe auch

Verzeichnissteuerelement
_searchenv, _wsearchenv
getenv, _wgetenv
_putenv, _wputenv