getenv_s, _wgetenv_s

Ruft einen Wert aus der aktuellen Umgebung ab. Diese Versionen von getenv, _wgetenv enthalten Sicherheitserweiterungen, wie unter Sicherheitsfunktionen in der CRT beschrieben.

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
  Der Puffer, dem der Wert der Umgebungsvariablen zu speichern.

• numberOfElements
  Größe von buffer.

• varname
  Umgebungsvariablenname.

Rückgabewert

Null wenn erfolgreich; andernfalls ein Fehlercode auf Fehler.

Fehlerbedingungen

Alle Fehlerzustände ruft einen ungültigen Parameterhandler auf, wie in Parametervalidierung beschrieben. Wenn die weitere Ausführung zugelassen wird, legen die Funktionen errno auf EINVAL fest und geben EINVAL zurück.

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

Hinweise

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

_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. 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.

Entsprechend in einem Programm, Unicode- (_wmain) ist _environ zunächst 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, muss das Laufzeitsystem beide Kopien beibehalten, und dieses verursacht langsameren Ausführungszeit. Wenn Sie _putenv aufrufen, wird ein Aufruf an _wputenv auch automatisch ausgeführt, sodass sich die beiden Umgebungszeichenfolgen entsprechen.

In C++ wird die Verwendung dieser Funktionen von Vorlagenüberladungen vereinfacht; Überladungen können die Pufferlänge automatisch ableiten und die Anforderung und beseitigen, einem Größenargument anzugeben. Weitere Informationen finden Sie unter Sichere Vorlagenüberladungen.

Zuordnung generischer Textroutinen

Um den Wert der Umgebungsvariablen TZ, der mit getenv_s, _putenv und _tzset überprüfen oder ändern, nach Bedarf. Weitere Informationen zu TZ finden Sie unter _tzset und _daylight, _dstbias, _timezone und _tzname.

Anforderungen

Zusätzliche 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);
}

.NET Framework-Entsprechung

System::Environment::GetEnvironmentVariable

Siehe auch

Referenz

Prozess- und Umgebungssteuerung

Umgebungskonstanten

_putenv, _wputenv

_dupenv_s, _wdupenv_s