strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l - gibt eine
Zeichenkette zurück, die den Fehlercode beschreibt
Standard-C-Bibliothek (
libc,
-lc)
#include <string.h>
char *strerror(int fehlernum);
const char *strerrorname_np(int fehlernum);
const char *strerrordesc_np(int fehlernum);
int strerror_r(int fehlernum, char puf[.puflänge], size_t buflen);
/* XSI-konform */
char *strerror_r(int fehlernum, char puf[.puflänge], size_t puflänge);
/* GNU-spezifisch */
char *strerror_l(int fehlernum, locale_t locale);
strerrorname_np(),
strerrordesc_np():
_GNU_SOURCE
strerror_r():
Die XSI-konforme Version wird bereitgestellt, falls:
(_POSIX_C_SOURCE >= 200112L) && ! _GNU_SOURCE
Anderenfalls wird die GNU-spezifische Version bereitgestellt.
Die Funktion
strerror() gibt einen Zeiger auf eine Zeichenkette mit der
Beschreibung des Fehlercodes für das übergebene Argument
fehlernum zurück. Möglicherweise wertet sie dabei den
LC_MESSAGES-Teil der aktuellen Locale aus, um die passende Sprache zu
wählen. (Falls beispielsweise
fehlernum EINVAL ist, dann
wird die zurückgelieferte Beschreibung »Invalid argument«
sein.). Diese Zeichenkette darf nicht von der Anwendung verändert
werden, wohl aber von einem nachfolgenden Aufruf von
strerror() oder
strerror_l(). Diese Zeichenkette wird von keiner anderen
Bibliotheksfunktion, inklusive
perror(3), verändert.
Wie
strerror() gibt die Funktion
strerrordesc_np() einen Zeiger
auf eine Zeichenkette zurück, die den Fehlercode des im Argument
fehlernum übergebenen Fehlers enthält, jedoch mit dem
Unterschied, dass die zurückgegebene Zeichenkette nicht anhand der
aktuellen Locale übersetzt ist.
Die Funktion
strerrorname_np() gibt einen Zeiger auf eine Zeichenkette
zurück, die den Namen des im Argument
fehlernum
übergebenen Fehlers enthält. Ist beispielsweise
EPERM als
Argument angegeben, gibt diese Funktion einen Zeiger auf die Zeichenkette
»EPERM« zurück.
Die Funktion
strerror_r() ähnelt
strerror(), ist aber
threadsicher. Diese Funktion ist in zwei Versionen verfügbar: eine in
POSIX.1-2001 beschriebene XSI-konforme Version (verfügbar seit Glibc
2.3.4, aber vor Glibc 2.13 nicht POSIX-konform) und eine GNU-spezifische
Version (verfügbar seit Glibc 2.0). Die XSI-konforme Version wird durch
die in der ÜBERSICHT angegebenen Feature-Test-Makroeinstellungen
bereitgestellt; anderenfalls wird die GNU-Version verwendet. Ohne explizit
vereinbarte Feature-Test-Makros wird (seit Glibc 2.4)
standardmäßig
_POSIX_C_SOURCE mit dem Wert 200112L
belegt, sodass standardmäßig die XSI-Variante von
strerror_r() verwendet wird.
Die XSI-konforme
strerror_r() ist für portable Anwendungen
vorzuziehen. Sie gibt die Fehlerzeichenkette im vom Nutzer bereitgestellten
Puffer
puf der Länge
puflänge zurück.
Die GNU-spezifische
strerror_r() gibt einen Zeiger auf eine Zeichenkette
zurück, die die Fehlernachricht enthält. Dies kann entweder ein
Zeiger auf eine Zeichenkette sein, die die Funktion in
puf speichert,
oder ein Zeiger auf irgendeine (unveränderbare statische)
Zeichenkette(wobei dann
puf nicht genutzt wird). Wenn die Funktion in
puf eine Zeichenkette speichert, werden höchstens
puflänge Bytes gespeichert (die Zeichenkette kann gekürzt
werden, wenn
puflänge zu klein und
fehlernum unbekannt
ist). Die Zeichenkette enthält immer ein abschließendes Nullbyte
(»\0«).
strerror_l() verhält sich wie
strerror(), aber weist
fehlernum einer locale-abhängigen Fehlermeldung in der durch
locale angegebenen Locale zu. Das Verhalten von
strerror_l() ist
nicht definiert, wenn
locale das spezielle Locale-Objekt
LC_GLOBAL_LOCALE ist oder kein gültiges Handle für ein
Locale-Objekt.
Die Funktionen
strerror(),
strerror_l() und die GNU-spezifische
strerror_r() geben die entsprechende Zeichenkette mit der
Fehlerbeschreibung zurück oder eine Nachricht »Unbekannter
Fehler nnn«, wenn die Fehlernummer unbekannt ist.
Bei Erfolg geben
strerrorname_np() und
strerrordesc_np() die
entsprechende den Fehler beschreibende Zeichenkette zurück. Falls
fehlernum eine unzulässige Fehlernummer ist, geben diese
Funktionen NULL zurück.
Die XSI-konforme Funktion
strerror_r() gibt bei Erfolg 0 zurück.
Im Fehlerfall wird eine positive Fehlernummer (seit Glibc 2.13) oder -1
zurückgegeben und
errno mit einem Wert belegt, der den Fehler
angibt (Glibc vor Version 2.13).
POSIX.1-2001 und POSIX.1-2008 verlangen, dass ein erfolgreicher Aufruf von
strerror() oder
strerror_l()
errno unverändert
belässt. Sie merken an, dass wegen des nicht definierten
Rückgabewerts zur Anzeige eines Fehlers eine Anwendung zur
Fehlerprüfung vor dem Aufruf
errno auf Null setzen und nach dem
Aufruf überprüfen sollte.
- EINVAL
- Der Wert von fehlernum ist keine gültige
Fehlernummer.
- ERANGE
- Es wurde unzureichender Speicher für die Aufnahme
der Fehler-Zeichenkette bereitgestellt.
Die Funktion
strerror_l() kamen erstmals in Glibc 2.6 vor.
Die Funktionen
strerrorname_np() und
strerrordesc_np() kamen
erstmals in Glibc 2.32 vor.
Siehe
attributes(7) für eine Erläuterung der in diesem
Abschnitt verwandten Ausdrücke.
| Schnittstelle |
Attribut |
Wert |
|
strerror() |
Multithread-Fähigkeit |
MT-Unsafe race:strerror |
|
strerrorname_np(), strerrordesc_np() |
Multithread-Fähigkeit |
MT-Safe |
|
strerror_r(), strerror_l() |
Multithread-Fähigkeit |
MT-Safe |
strerror() wird von POSIX.1-2001, POSIX.1-2008 und C99 spezifiziert.
strerror_r() wird von POSIX.1-2001 spezifiziert.
strerror_l() ist in POSIX.1-2008 spezifiziert.
Die GNU-spezifischen Funktionen
strerror_r(),
strerrorname_np()
und
strerrordesc_np() sind eine nicht standardisierte Erweiterungen.
POSIX.1-2001 gestattet
strerror() das Setzen von
errno wenn der
Aufruf einen Fehler bewirkt, gibt aber nicht vor, welchen Wert die Funktion im
Fehlerfall zurückgeben sollte. Auf einigen Systemen gibt
strerror() NULL zurück, wenn die Fehlernummer nicht bekannt ist.
Auf anderen Systemen gibt
strerror() eine Meldung etwa wie
»Fehler nnn aufgetreten« und setzt
errno auf
EINVAL, wenn die Fehlernummer unbekannt ist. C99 und POSIX.1-2008
verlangen, dass der Rückgabewert von NULL verschieden ist.
Die GNU-C-Bibliothek verwendet einen Puffer von 1024 Zeichen für
strerror(). Diese Puffergröße sollte daher ausreichen, um
einen Fehler
ERANGE beim Aufruf von
strerror_r() zu vermeiden.
strerrorname_np() und
strerrordesc_np() sind weder
multithread-fähig noch asynchronsignalsicher.
err(3),
errno(3),
error(3),
perror(3),
strsignal(3),
locale(7)
Die deutsche Übersetzung dieser Handbuchseite wurde von Martin Eberhard
Schauer <
[email protected]> und Mario Blättermann
<
[email protected]> erstellt.
Diese Übersetzung ist Freie Dokumentation; lesen Sie die
GNU
General Public License Version 3 oder neuer bezüglich der
Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.
Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken
Sie bitte eine E-Mail an die
Mailingliste
der Übersetzer