_searchenv_s, _wsearchenv_s

Artikel
03/12/2013

Sucht eine Datei mit der Umgebungspfade.Diese sind Versionen von _searchenv, _wsearchenv mit Sicherheitserweiterungen, wie in Sicherheitsfeatures im CRT beschrieben.

Wichtig
Diese API kann nicht in den Anwendungen verwendet werden, die in der Windows Runtime ausführen.Weitere Informationen finden Sie unter CRT-Funktionen unterstützt nicht mit /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

Parameter

[in] filename
Name der zu suchenden Datei.
[in] varname
Zum Suchen Umgebung.
[out] pathname
Der Puffer, dem des vollständigen Pfads zu speichern.
[in] numberOfElements
Größe des pathname Puffers.

Rückgabewert

Null erfolgreich, wenn ein Fehlercode auf Fehler.

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

Fehlerbedingungen

filename	varname	pathname	numberOfElements	Rückgabewert	Inhalt von pathname
any	any	NULL	any	EINVAL	nicht verfügbar
NULL	any	any	any	EINVAL	nicht geändert
any	any	any	<= 0	EINVAL	nicht geändert

Wenn eine dieser Fehlerbedingungen auftritt, wird der ungültige Parameterhandler aufgerufen, wie in Parametervalidierung beschrieben.Wenn die Ausführung zulässig ist, um fortzufahren, legen diese Funktionen errno auf EINVAL fest und geben EINVAL zurück.

Hinweise

Die _searchenv_s Routinensuchen für die Zieldatei in der angegebenen Domäne.Die varname-Variable kann jede Umgebung oder benutzerdefinierte Variable sein, die eine Liste von Verzeichnispfaden, wie PATH, LIB und INCLUDE angibt.Da _searchenv_s die Groß-/Kleinschreibung beachtet wird, sollte varname den Fall von der Umgebungsvariablen übereinstimmen.Wenn varname nicht den Namen einer Umgebungsvariable übereinstimmt, die in der Umgebung des Prozesses definiert ist, gibt die Funktion null zurück und die pathname-Variable ist unverändert.

Die Routine durchsucht zuerst für die Datei im aktuellen Arbeitsverzeichnis.Wenn sie nicht die Datei findet, wird sie als Nächstes durch die Verzeichnisse, die in der - Umgebungsvariablen angegeben werden.Wenn die Zieledatei in einem dieser Verzeichnisse ist, wird der neu erstellte Pfad in pathname kopiert.Wenn die filename Datei nicht gefunden wird, enthält pathname eine leere auf NULL endende Zeichenfolge.

Der pathname Puffer sollte _MAX_PATH Zeichen mindestens sein, lang, um das in voller Länge des erstellten Pfadnamens angepasst.Andernfalls überliefe möglicherweise _searchenv_s den pathname Puffer mit dem Ergebnis des unerwarteten Verhaltens.

_wsearchenv_s ist eine Breitzeichen-Version von _searchenv_s; die Argumente zu _wsearchenv_s sind Breitzeichen-Zeichenfolgen._wsearchenv_s und _searchenv_s verhalten sich andernfalls identisch.

In C++ mithilfe dieser Funktionen wird durch Vorlagenüberladungen vereinfacht; die Überladungen können die Pufferlänge (die Anforderung automatisch beseitigend ableiten, ein Größenargument anzugeben) und können die älteren, nicht-sicheren Funktionen durch ihre späteren, sicheren Entsprechungen automatisch ersetzen.Weitere Informationen finden Sie unter Speichern Sie Vorlagen-Überladungen.

Zuordnung generische 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 Kompatibilitätsinformation finden Sie unter Kompatibilität in der Einführung.

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

.NET Framework-Entsprechung

Nicht zutreffend. Um die Standard-C-Funktion aufzurufen, verwenden Sie PInvoke. Weitere Informationen finden Sie unter Beispiele für Plattformaufrufe.