strerror, strerror_s, strerrorlen_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

 

Bibliothek für Zeichenketten

Null-terminierte Byte-Strings

Null-terminierte Multibyte-Strings

Null-terminierte breite Zeichenketten

 

Null-terminierte Byte-Strings

Funktionen
Zeichenmanipulation
isalnum isalpha islower isupper isdigit isxdigit isblank (C99)	iscntrl isgraph isspace isprint ispunct tolower toupper
Konvertierungen zu und von numerischen Formaten
atoiatolatoll (C99) atof strtolstrtoll (C99) strtoulstrtoull (C99)	strtoimaxstrtouimax (C99)(C99) strtofstrtodstrtold (C99)(C99) strfromfstrfromdstrfroml (C23)(C23)(C23)
Stringmanipulation
strcpystrcpy_s (C11) strncpystrncpy_s (C11) strcatstrcat_s (C11)	strncatstrncat_s (C11) strxfrm strdup (C23) strndup (C23)
Stringuntersuchung
strlenstrnlen_s (C11) strcmp strncmp strcoll strchr strrchr	strspn strcspn strpbrk strstr strtokstrtok_s (C11)
Speichermanipulation
memchr memcmp memsetmemset_explicitmemset_s (C23)(C11)	memcpymemcpy_s (C11) memmovememmove_s (C11) memccpy (C23)
Sonstiges
strerrorstrerror_sstrerrorlen_s (C11)(C11)

 

Definiert in Header <string.h>
char* strerror( int errnum );	(1)
errno_t strerror_s( char *buf, rsize_t bufsz, errno_t errnum );	(2)	(seit C11)
size_t strerrorlen_s( errno_t errnum );	(3)	(seit C11)

1) Gibt einen Zeiger auf die textuelle Beschreibung des Systemfehlercodes errnum zurück, identisch mit der Beschreibung, die von perror() ausgegeben würde.

errnum wird normalerweise aus der errno Variablen bezogen, jedoch akzeptiert die Funktion jeden Wert vom Typ int. Der Inhalt der Zeichenkette ist gebietsspezifisch.

Die zurückgegebene Zeichenkette darf vom Programm nicht verändert werden, kann aber durch einen nachfolgenden Aufruf der Funktion strerror überschrieben werden. strerror muss nicht threadsicher sein. Implementierungen können unterschiedliche Zeiger auf statische schreibgeschützte Zeichenkettenliterale zurückgeben oder immer denselben Zeiger zurückgeben, der auf einen statischen Puffer zeigt, in den strerror die Zeichenkette schreibt.

2) Wie (1), außer dass die Nachricht in den vom Benutzer bereitgestellten Speicher buf kopiert wird. Es werden nicht mehr als bufsz-1 Bytes geschrieben, der Puffer wird immer nullterminiert. Wenn die Nachricht abgeschnitten werden musste, um in den Puffer zu passen, und bufsz größer als 3 ist, dann werden nur bufsz-4 Bytes geschrieben und die Zeichen "..." werden vor dem Nullterminator angehängt. Zusätzlich werden die folgenden Fehler zur Laufzeit erkannt und rufen die aktuell installierte Constraint-Handler-Funktion auf:

• buf ist ein Nullzeiger
• bufsz ist null oder größer als RSIZE_MAX

Das Verhalten ist undefiniert, wenn das Schreiben in buf über das Ende des Arrays hinaus erfolgt, was passieren kann, wenn die Größe des von buf zeigenden Puffers kleiner ist als die Anzahl der Zeichen in der Fehlermeldung, die wiederum kleiner ist als bufsz.

3) Berechnet die Länge der unverkürzten gebietsspezifischen Fehlermeldung, die strerror_s schreiben würde, wenn sie mit errnum aufgerufen würde. Die Länge enthält nicht den Nullterminator.

Wie bei allen grenzgeprüften Funktionen sind strerror_s und strerrorlen_s nur dann garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert wird und wenn der Benutzer __STDC_WANT_LIB_EXT1__ vor dem Einbinden von <string.h> auf die ganzzahlige Konstante 1 setzt.

Parameter

errnum	-	Ganzzahliger Wert, der sich auf einen Fehlercode bezieht
buf	-	Zeiger auf einen vom Benutzer bereitgestellten Puffer
bufsz	-	Größe des vom Benutzer bereitgestellten Puffers

Rückgabewert

1) Zeiger auf eine nullterminierte Bytezeichenkette, die dem errno-Fehlercode errnum entspricht.

2) Null, wenn die gesamte Nachricht erfolgreich in buf gespeichert wurde, ungleich Null andernfalls.

3) Länge (ohne Nullterminator) der Nachricht, die strerror_s zurückgeben würde

Anmerkungen

POSIX erlaubt, dass nachfolgende Aufrufe von strerror den von einem früheren Aufruf zurückgegebenen Zeigerwert ungültig machen. Es gibt auch an, dass das LC_MESSAGES-Gebietsschema-Facet den Inhalt dieser Nachrichten steuert.

strerror_s ist die einzige grenzgeprüfte Funktion, die Kürzung zulässt, da die Bereitstellung möglichst vieler Informationen über einen Fehler als wünschenswerter erachtet wurde. POSIX definiert auch strerror_r für ähnliche Zwecke.

Beispiel

Führen Sie diesen Code aus

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <locale.h>
 
int main(void)
{
    FILE *fp = fopen(tmpnam((char[L_tmpnam]){0}), "r");
    if(fp==NULL) {
        printf("File opening error: %s\n", strerror(errno));
        setlocale(LC_MESSAGES, "de_DE.utf8");
        printf("Now in German: %s\n", strerror(errno));
#ifdef __STDC_LIB_EXT1__
        setlocale(LC_ALL, "ja_JP.utf8"); // printf needs CTYPE for multibyte output
        size_t errmsglen = strerrorlen_s(errno) + 1;
        char errmsg[errmsglen]; 
        strerror_s(errmsg, errmsglen, errno);
        printf("Now in Japanese: %s\n", errmsg);
#endif
    }
}

Mögliche Ausgabe

File opening error: No such file or directory
Now in German: Datei oder Verzeichnis nicht gefunden
Now in Japanese: そのようなファイル、又はディレクトリはありません

Referenzen

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

• 7.24.6.2 The strerror function (p: 371)

• K.3.7.4.2 The strerror_s function (p: 622)

• K.3.7.4.3 The strerrorlen_s function (p: 623)

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

• 7.21.6.2 The strerror function (p: 334)

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

• 4.11.6.2 The strerror function

Siehe auch

perror	zeigt einen Zeichenstring, der dem aktuellen Fehler entspricht, nach stderr an (Funktion)
errno	Makro, das zur POSIX-kompatiblen, Thread-lokalen Fehlernummern-Variable expandiert (Makrovariable)
C++-Dokumentation für strerror