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 |
any | Beliebig | Beliebig | EINVAL |
| any | NULL |
>0 | any | EINVAL |
| Beliebig | Beliebig | any | 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 verwalten muss. Beispielsweise erfolgt bei einem Aufruf von _putenv automatisch auch ein Aufruf von _wputenv, damit die beiden Umgebungszeichenfolgen übereinstimmen.
Achtung
In seltenen Fällen, wenn das Laufzeitsystem sowohl eine Unicodeversion als auch eine Multibyteversion der Umgebung verwaltet, stimmen diese zwei Versionen möglicherweise nicht exakt überein. 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 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 |
|---|---|---|---|
_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