getenv_s, _wgetenv_s

Artikel
03/12/2013

Ruft einen Wert aus der aktuellen Umgebung ab.Diese Versionen von getenv, _wgetenv haben Sicherheitserweiterungen, wie in Sicherheitsfeatures im CRT beschrieben.

Wichtig
Diese API kann nicht in den Anwendungen verwendet werden, die in Windows-Runtime ausführen.Weitere Informationen finden Sie unter CRT-Funktionen unterstützt nicht mit /ZW.

errno_t getenv_s( size_t *pReturnValue, char* buffer, size_t numberOfElements, const char *varname ); errno_t _wgetenv_s( size_t *pReturnValue, wchar_t *buffer, size_t numberOfElements, const wchar_t *varname ); template <size_t size> errno_t getenv_s( size_t *pReturnValue, char (&buffer)[size], const char *varname ); // C++ only template <size_t size> errno_t _wgetenv_s( size_t *pReturnValue, wchar_t (&buffer)[size], const wchar_t *varname ); // C++ only

Parameter

pReturnValue
Die Puffergröße, die erforderlich ist oder 0, wenn die Variable nicht gefunden wird.
buffer
Puffer, in der der Wert der Umgebungsvariablen zu speichern.
numberOfElements
Größe von buffer.
varname
Umgebungsvariablenname.

Rückgabewert

Null erfolgreich, wenn andernfalls ein Fehlercode auf Fehler.

Fehlerbedingungen

pReturnValue	buffer	numberOfElements	varname	Rückgabewert
NULL	any	any	any	EINVAL
any	NULL	>0	any	EINVAL
any	any	any	NULL	EINVAL

Alle Fehlerbedingungen ruft einen ungültigen Parameterhandler auf, wie in Parametervalidierung beschrieben.Wenn die Ausführung zulässig ist, um fortzufahren, legen die Funktionen errno auf EINVAL fest und geben EINVAL zurück.

Wenn der Puffer zu klein ist, geben diese Funktionen ERANGE zurück.Sie rufen keinen ungültigen Parameterhandler auf.Sie schreiben die erforderliche Puffergröße in pReturnValue aus und aktivieren insofern Programme, um die Funktion mit einem größeren Puffer erneut aufzurufen.

Hinweise

Die getenv_s-Funktion sucht die Liste der Umgebungsvariablen für varname.getenv_s ist nicht im Windows-Betriebssystem die Groß-/Kleinschreibung beachtet.getenv_s und _putenv_s verwenden die Kopie der Umgebung, die durch die globale Variable _environ dargestellt werden, um auf die Umgebung auf.getenv_s kann nur für den Datenstrukturen, die der Laufzeitbibliothek und nicht auf der Umgebung "Segment" zugegriffen werden kann, die für den Prozess vom Betriebssystem erstellt wird.Daher könnten Programme, die das envp-Argument zu Haupt- oder zu wmain verwenden, ungültige Informationen ab.

_wgetenv_s ist eine Breitzeichen-Version von getenv_s; das Argument und der Rückgabewert von _wgetenv_s sind Breitzeichen-Zeichenfolgen.Die globale Variable _wenviron ist eine Breitzeichen-Version von _environ.

In einem MBCS-Programm (beispielsweise, in einem SBCS-ASCII-Programm), ist _wenviron zuerst NULL, da die Umgebung von Mehrbyte-Zeichenfolgen besteht.Anschließend beim ersten Aufruf von _wputenv oder beim ersten Aufruf von _wgetenv_s, wenn eine Umgebung (MBCS) bereits vorhanden ist, wird eine entsprechende Breitzeichen-Umgebung erstellt und wird anschließend durch _wenviron gezeigt.

Ähnlich wie in einem Unicode-(_wmain)-Programm ist _environ zuerst NULL, da die Umgebung aus Zeichenfolgen mit Breitzeichen besteht.Anschließend beim ersten Aufruf von _putenv oder beim ersten Aufruf von getenv_s, wenn Umgebung ein (Unicode) bereits vorhanden ist, wird eine entsprechende MBCS-Umgebung erstellt und wird anschließend durch _environ gezeigt.

Wenn zwei Kopien der Umgebung (MBCS und Unicode) gleichzeitig in einem Programm vorhanden sind, muss das Laufzeitsystem beide Kopien beibehalten, und dieses verursacht langsamere Ausführungszeit.Wenn Sie beispielsweise _putenv aufrufen, wird ein Aufruf _wputenv auch automatisch ausgeführt, sodass die zwei Umgebungszeichenfolgen entsprechen.

Vorsicht
In seltenen Fällen wenn das Laufzeitsystem eine Unicode-Version und eine - Version der Umgebung verwaltet werden, entsprechen die zwei Umgebungsversionen möglicherweise nicht genau.Dies geschieht, weil, obwohl keine eindeutigen Mehrbyte-Zeichenfolgen-Zuordnungen zu einer eindeutigen Unicode-Zeichenfolge, die Zuordnung von einer eindeutigen Unicode-Zeichenfolge in einer Mehrbyte-Zeichenfolge nicht unbedingt eindeutig ist.Weitere Informationen finden Sie unter _environ, _wenviron.

In seltenen Fällen wenn das Laufzeitsystem eine Unicode-Version und eine - Version der Umgebung verwaltet werden, entsprechen die zwei Umgebungsversionen möglicherweise nicht genau.Dies geschieht, weil, obwohl keine eindeutigen Mehrbyte-Zeichenfolgen-Zuordnungen zu einer eindeutigen Unicode-Zeichenfolge, die Zuordnung von einer eindeutigen Unicode-Zeichenfolge in einer Mehrbyte-Zeichenfolge nicht unbedingt eindeutig ist.Weitere Informationen finden Sie unter _environ, _wenviron.

Hinweis
Die _putenv_s und _getenv_s Familien von Funktionen sind nicht threadsicher._getenv_s konnte einen Zeichenfolgenzeiger zurückgeben, während _putenv_s die Zufallsausfälle der Zeichenfolge und dadurch die Ursache ändert.Überprüfen Sie, ob Aufrufe dieser Funktionen synchronisiert werden.

In C++ wird die Verwendung dieser Funktionen durch Vorlagenüberladungen vereinfacht; die Überladungen können Pufferlänge automatisch ableiten und die Anforderung insofern vermeiden, ein Größenargument anzugeben.Weitere Informationen finden Sie unter Speichern Sie Vorlagen-Überladungen.

Zuordnung generische Textroutinen

TCHAR.H-Routine	_UNICODE & _MBCS nicht definiert.	_MBCS definiert	_UNICODE definiert
_tgetenv_s	getenv_s	getenv_s	_wgetenv_s

So legen Sie den Wert der TZ Umgebungsvariable, Verwendung getenv_s, des _putenv und des _tzset überprüfen oder ändern, nach Bedarf.Weitere Informationen zu TZ finden Sie unter _tzset und _daylight, _dstbias, _timezone und _tzname.

Anforderungen

Routine	Erforderlicher Header
getenv_s	<stdlib.h>
_wgetenv_s	<stdlib.h> oder <wchar.h>

So zusätzlicher Kompatibilitätsinformation finden Sie unter Kompatibilität.

Beispiel

// crt_getenv_s.c
// This program uses getenv_s to retrieve
// the LIB environment variable and then uses
// _putenv to change it to a new value.
 
#include <stdlib.h>
#include <stdio.h>

int main( void )
{
   char* libvar;
   size_t requiredSize;

   getenv_s( &requiredSize, NULL, 0, "LIB");
   if (requiredSize == 0)
   {
      printf("LIB doesn't exist!\n");
      exit(1);
   }

   libvar = (char*) malloc(requiredSize * sizeof(char));
   if (!libvar)
   {
      printf("Failed to allocate memory!\n");
      exit(1);
   }

   // Get the value of the LIB environment variable.
   getenv_s( &requiredSize, libvar, requiredSize, "LIB" );

   printf( "Original LIB variable is: %s\n", libvar );

   // Attempt to change path. Note that this only affects
   // the environment variable of the current process. The command
   // processor's environment is not changed.
   _putenv_s( "LIB", "c:\\mylib;c:\\yourlib" );

   getenv_s( &requiredSize, NULL, 0, "LIB");

   libvar = (char*) realloc(libvar, requiredSize * sizeof(char));
   if (!libvar)
   {
      printf("Failed to allocate memory!\n");
      exit(1);
   }

   // Get the new value of the LIB environment variable. 
   getenv_s( &requiredSize, libvar, requiredSize, "LIB" );

   printf( "New LIB variable is: %s\n", libvar );

   free(libvar);
}