getenv, getenv_s

 

C

Compiler-Unterstützung

Sprache

Header

Typunterstützung

Programm-Dienstprogramme

Unterstützung für variable Funktionsargumente

Fehlerbehandlung

Dynamische Speicherverwaltung

Bibliothek für Zeichenketten

Algorithmen

Numerik

Datums- und Zeitdienstprogramme

Ein-/Ausgabeunterstützung

Lokalisierungsunterstützung

Unterstützung für Nebenläufigkeit (C11)

Technische Spezifikationen

Symbolindex

 

Programm-Support-Dienstprogramme

Programmabbruch
abort exit quick_exit (C11) _Exit (C99)	atexit at_quick_exit (C11) EXIT_SUCCESSEXIT_FAILURE
Unerreichbarer Kontrollfluss
unreachable (C23)
Kommunikation mit der Umgebung
getenvgetenv_s (C11)	system
Abfrage der Speicher-Ausrichtung
memalignment (C23)
Signale
signal raise sig_atomic_t	SIG_DFLSIG_IGN SIG_ERR
Signalarten
SIGABRTSIGFPESIGILL	SIGINTSIGSEGVSIGTERM
Nicht-lokale Sprünge
setjmp	longjmp
Typen
jmp_buf

 

Definiert im Header <stdlib.h>
char *getenv( const char *name );	(1)
errno_t getenv_s( size_t *restrict len, char *restrict value,                   rsize_t valuesz, const char *restrict name );	(2)	(seit C11)

1) Sucht in der vom Host vorgegebenen Umgebungsvariablenliste nach einer Umgebungsvariable mit dem Namen name und gibt einen Zeiger auf den String zurück, der mit der übereinstimmenden Umgebungsvariablen assoziiert ist. Die Menge der Umgebungsvariablen und die Methoden zur Änderung sind implementierungsabhängig.

Diese Funktion muss nicht Thread-sicher sein. Ein weiterer Aufruf von getenv sowie ein Aufruf der POSIX-Funktionen setenv(), unsetenv() und putenv() können den von einem vorherigen Aufruf zurückgegebenen Zeiger ungültig machen oder den von einem vorherigen Aufruf erhaltenen String modifizieren.

Das Modifizieren des von getenv zurückgegebenen Strings führt zu undefiniertem Verhalten.

2) Ähnlich wie (1), mit der Ausnahme, dass die Werte der Umgebungsvariable in den vom Benutzer bereitgestellten Puffer value geschrieben werden (sofern nicht null) und die Anzahl der geschriebenen Bytes an der vom Benutzer bereitgestellten Stelle *len gespeichert wird (sofern nicht null). Wenn die Umgebungsvariable in der Umgebung nicht gesetzt ist, wird Null in *len geschrieben (sofern nicht null) und '\0' wird in value[0] geschrieben (sofern nicht null). Darüber hinaus werden die folgenden Fehler zur Laufzeit erkannt und die aktuell installierte Constraint-Handler-Funktion aufgerufen:

• name ist ein Nullzeiger
• valuesz ist größer als RSIZE_MAX
• value ist ein Nullzeiger und valuesz ist nicht Null

Wie bei allen grenzgeprüften Funktionen ist getenv_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert wird und wenn der Benutzer __STDC_WANT_LIB_EXT1__ vor dem Einbinden von <stdlib.h> auf die Ganzzahlkonstante 1 setzt.

Parameter

name	-	null-terminierter Zeichenstring, der den Namen der zu suchenden Umgebungsvariable identifiziert
len	-	Zeiger auf eine vom Benutzer bereitgestellte Stelle, an der getenv_s die Länge der Umgebungsvariable speichert
value	-	Zeiger auf ein vom Benutzer bereitgestelltes Zeichenarray, in das getenv_s den Inhalt der Umgebungsvariable speichert
valuesz	-	maximale Anzahl von Zeichen, die getenv_s in dest schreiben darf (Größe des Puffers)

Rückgabewert

1) Zeichenstring, der den Wert der Umgebungsvariable identifiziert, oder ein Nullzeiger, wenn eine solche Variable nicht gefunden wurde.

2) Null, wenn die Umgebungsvariable gefunden wurde, ungleich Null, wenn sie nicht gefunden wurde oder wenn eine Laufzeitbeschränkungsverletzung aufgetreten ist. Bei jedem Fehler wird Null in *len geschrieben (sofern len kein Nullzeiger ist).

Hinweise

Auf POSIX-Systemen sind die Umgebungsvariablen auch über die globale Variable environ zugänglich, deklariert als extern char **environ; in <unistd.h>, und über das optionale dritte Argument, envp, der main-Funktion.

Der Aufruf von getenv_s mit einem Nullzeiger für value und Null für valuesz wird verwendet, um die Größe des Puffers zu ermitteln, der benötigt wird, um das gesamte Ergebnis aufzunehmen.

Beispiel

Führen Sie diesen Code aus

#include <stdio.h>
#include <stdlib.h>
 
int main(void)
{
    const char *name = "PATH";
    const char *env_p = getenv(name);
    if (env_p)
        printf("Your %s is %s\n", name, env_p);
}

Mögliche Ausgabe

Your PATH is /home/gamer/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/share/games

Referenzen

• C23-Standard (ISO/IEC 9899:2024)

• 7.22.4.6 Die Funktion getenv (S: TBD)

• K.3.6.2.1 Die Funktion getenv_s (S: TBD)

• C17-Standard (ISO/IEC 9899:2018)

• 7.22.4.6 Die Funktion getenv (S: 256-257)

• K.3.6.2.1 Die Funktion getenv_s (S: 440-441)

• C11-Standard (ISO/IEC 9899:2011)

• 7.22.4.6 Die Funktion getenv (S: 352-353)

• K.3.6.2.1 Die Funktion getenv_s (S: 606-607)

• C99-Standard (ISO/IEC 9899:1999)

• 7.20.4.5 Die Funktion getenv (S: 317)

• C89/C90-Standard (ISO/IEC 9899:1990)

• 4.10.4.4 Die Funktion getenv

Siehe auch

C++ Dokumentation für getenv