Namespaces
Variants

strerror, strerror_s, strerrorlen_s

From cppreference.net
< c ‎ | string ‎ | byte
C
Strings library
Null-terminated byte strings
Functions
Character manipulation
Conversions to and from numeric formats
String manipulation
String examination
Memory manipulation
Miscellaneous
strerror strerror_s strerrorlen_s
(C11) (C11)
Definiert im 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 werden würde.
errnum wird üblicherweise aus der Variable errno bezogen, jedoch akzeptiert die Funktion jeden Wert vom Typ int . Der Inhalt der Zeichenkette ist localespezifisch.
Der zurückgegebene String darf vom Programm nicht modifiziert werden, kann jedoch durch einen nachfolgenden Aufruf der strerror -Funktion überschrieben werden. strerror muss nicht thread-sicher sein. Implementierungen können verschiedene Zeiger auf statische schreibgeschützte String-Literale zurückgeben oder immer wieder denselben Zeiger zurückgeben, der auf einen statischen Puffer zeigt, in dem strerror den String platziert.
2) Gleich wie (1) , außer dass die Nachricht in den benutzerbereitgestellten Speicher buf kopiert wird. Es werden maximal bufsz-1 Bytes geschrieben, der Puffer ist immer nullterminiert. Wenn die Nachricht gekürzt 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 "..." vor dem Nullterminator angehängt. Zusätzlich werden folgende 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 Puffers, auf den buf zeigt, kleiner ist als die Anzahl der Zeichen in der Fehlermeldung, die wiederum kleiner ist als bufsz .
3) Berechnet die Länge der ungekürzten lokalisierungsabhängigen Fehlermeldung, die strerror_s schreiben würde, wenn es mit errnum aufgerufen würde. Die Länge enthält den Nullterminator nicht.
Wie bei allen grenzprüfenden Funktionen sind strerror_s und strerrorlen_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ durch die Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf den Integer-Konstantenwert 1 setzt, bevor <string.h> eingebunden wird.

Inhaltsverzeichnis

Parameter

errnum - Integralwert, der sich auf einen Fehlercode bezieht
buf - Zeiger auf einen benutzerbereitgestellten Puffer
bufsz - Größe des benutzerbereitgestellten Puffers

Rückgabewert

1) Zeiger auf eine nullterminierte Byte-Zeichenkette, die dem errno Fehlercode errnum entspricht.
2) Null, wenn die gesamte Nachricht erfolgreich in buf gespeichert wurde, andernfalls ungleich null.
3) Länge (ohne den Nullterminator) der Nachricht, die strerror_s zurückgeben würde

Hinweise

POSIX erlaubt nachfolgende Aufrufe von strerror , den von einem früheren Aufruf zurückgegebenen Zeigerwert für ungültig zu erklären. Es wird ebenfalls spezifiziert, dass es der LC_MESSAGES -Locale-Facet ist, der den Inhalt dieser Nachrichten steuert.

strerror_s ist die einzige grenzprüfende Funktion, die eine Abschneidung erlaubt, da es als wünschenswerter erachtet wurde, so viele Informationen wie möglich über einen Fehler bereitzustellen. POSIX definiert ebenfalls strerror_r für ähnliche Zwecke.

Beispiel

Diesen Code ausführen 
#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 Die strerror-Funktion (S. 371)
  • K.3.7.4.2 Die strerror_s-Funktion (S. 622)
  • K.3.7.4.3 Die strerrorlen_s-Funktion (S. 623)
  • C99-Standard (ISO/IEC 9899:1999):
  • 7.21.6.2 Die strerror-Funktion (S. 334)
  • C89/C90-Standard (ISO/IEC 9899:1990):
  • 4.11.6.2 Die strerror-Funktion

Siehe auch

gibt eine Zeichenkette entsprechend dem aktuellen Fehler auf stderr aus
(Funktion)
Makro, das zu einer POSIX-kompatiblen thread-lokalen Fehlernummer-Variable expandiert
(Makro-Variable)
C++-Dokumentation für strerror