getenv_s, _wgetenv_s

Ruft einen Wert aus der aktuellen Umgebung ab. Diese Versionen von getenv, _wgetenv 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 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 erforderliche Puffergröße oder 0, wenn die Variable nicht gefunden wird.

buffer
Puffer zum Speichern des Werts der Umgebungsvariablen.

numberOfElements
Größe von buffer.

varname
Umgebungsvariablenname.

Rückgabewert

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

Fehlerbedingungen

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

Eine dieser Fehlerbedingungen ruft einen ungültigen Parameterhandler auf, wie in der Parameterüberprüfung beschrieben. Wenn die weitere Ausführung zugelassen wird, legen die Funktionen errno auf EINVAL fest und geben EINVAL zurück.

Auch wenn der Puffer zu klein ist, geben diese Funktionen ERANGE zurück. Sie rufen keinen ungültigen Parameterhandler auf. Sie geben die erforderliche Puffergröße in pReturnValue aus und ermöglichen es dadurch Programmen, die Funktion erneut mit einem größeren Puffer aufzurufen.

Hinweise

Die getenv_s-Funktion sucht die Liste von Umgebungsvariablen für varname. getenv_s die Groß-/Kleinschreibung im Windows-Betriebssystem nicht beachtet wird. getenv_s und _putenv_s verwenden die Kopie der Umgebung, auf die die globale Variable _environ verweist, um auf die Umgebung zuzugreifen. getenv_s arbeitet nur auf den Datenstrukturen, auf die die Laufzeitbibliothek zugreifen kann, und nicht auf dem Umgebungssegment, das vom Betriebssystem für den Prozess erstellt wird. Daher können Programme, die das envp Argument main verwenden, ungültige Informationen abrufen oder wmain abrufen.

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

In einem MBCS-Programm (z. B. in einem SBCS-ASCII-Programm), ist _wenviron zunächst NULL, da die Umgebung aus den Multibyte-Zeichenfolgen besteht. Beim ersten Aufruf von _wputenv oder beim ersten Aufruf von _wgetenv_s (sofern bereits eine (MBCS)-Umgebung vorhanden ist), wird dann eine entsprechende Breitzeichenumgebung erstellt, auf die dann _wenviron verweist.

In einem Unicodeprogramm (_wmain) ist _environ dementsprechend NULL, da die Umgebung aus Zeichenfolgen mit Breitzeichen besteht. Beim ersten Aufruf von _putenv oder beim ersten Aufruf von getenv_s (sofern bereits eine (Unicode)-Umgebung vorhanden ist), wird dann eine entsprechende MBCS-Umgebung erstellt, auf die dann _environ verweist.

Wenn zwei Kopien der Umgebung (MBCS und Unicode) gleichzeitig in einem Programm vorhanden sind, kann die Ausführung länger dauern, da das Laufzeitsystem beide Kopien enthalten muss main. Beispielsweise erfolgt bei einem Aufruf von _putenv automatisch auch ein Aufruf von _wputenv, damit die beiden Umgebungszeichenfolgen übereinstimmen.

Achtung

Wenn das Laufzeitsystem mainin seltenen Fällen sowohl eine Unicode-Version als auch eine Multibyte-Version der Umgebung enthält, entsprechen die beiden Umgebungsversionen möglicherweise nicht genau. Dies liegt daran, dass die Zuordnung von einer eindeutigen Unicodezeichenfolge zu einer Multibyte-Zeichenfolge nicht unbedingt eindeutig ist, obwohl sich jede eindeutige Multibyte-Zeichenfolge einer eindeutigen Unicodezeichenfolge zuordnen lässt. Weitere Informationen finden Sie unter _environ, _wenvironverwalten.

Hinweis

Die Familien _putenv_s und _getenv_s der Funktionen sind nicht threadsicher. _getenv_s gibt möglicherweise einen Zeichenfolgenzeiger zurück, während _putenv_s die Zeichenfolge ändert, was zu zufälligen Fehlern führen kann. Stellen Sie sicher, dass Aufrufe dieser Funktionen synchronisiert sind.

Die Verwendung dieser Funktionen in C++ wird durch Vorlagenüberladungen vereinfacht. Überladungen können automatisch die Pufferlänge ableiten, sodass kein Größenargument angegeben werden muss. Weitere Informationen finden Sie unter "Sichere Vorlagenüberladungen".

Standardmäßig gilt der globale Zustand dieser Funktion für die Anwendung. Informationen zum Ändern dieses Verhaltens finden Sie im Global state in the CRT.

Generische Textroutinzuordnungen

TCHAR.H Routine	_UNICODE und _MBCS nicht definiert	_MBCS Definiert	_UNICODE Definiert
_tgetenv_s	getenv_s	getenv_s	_wgetenv_s

Um den Wert der Umgebungsvariablen TZ zu überprüfen oder zu ändern, verwenden Sie je nach Erfordernis getenv_s, _putenv und _tzset. Weitere Informationen zu TZ, siehe _tzset und_daylight , _dstbias, _timezoneund _tzname.

Anforderungen

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

Weitere Informationen zur Kompatibilität 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);
}

Original LIB variable is: c:\vctools\lib;c:\vctools\atlmfc\lib;c:\vctools\PlatformSDK\lib;c:\vctools\Visual Studio SDKs\DIA Sdk\lib;c:\vctools\Visual Studio SDKs\BSC Sdk\lib
New LIB variable is: c:\mylib;c:\yourlib

Siehe auch

Prozess- und Umgebungskontrolle
Umweltkonstanten
_putenv, _wputenv
_dupenv_s, _wdupenv_s