strerror_s, _strerror_s, _wcserror_s, __wcserror_s

Artikel
06/09/2015

Abrufen der Systemfehlermeldung (strerror_s_wcserror_s) oder Drucken einer vom Benutzer angegebenen Fehlermeldung (_strerror_s, __wcserror_s). Diese Versionen von strerror, _strerror, _wcserror, __wcserror enthalten Sicherheitserweiterungen wie unter Sicherheitsfunktionen in der CRT beschrieben.

errno_t strerror_s(
   char *buffer,
   size_t numberOfElements,
   int errnum 
);
errno_t _strerror_s(
   char *buffer,
   size_t numberOfElements,
   const char *strErrMsg 
);
errno_t _wcserror_s(
   wchar_t *buffer,
   size_t numberOfElements,
   int errnum 
);
errno_t __wcserror_s(
   wchar_t *buffer,
   size_t numberOfElements,
   const wchar_t *strErrMsg 
);
template <size_t size>
errno_t strerror_s(
   char (&buffer)[size],
   int errnum 
); // C++ only
template <size_t size>
errno_t _strerror_s(
   char (&buffer)[size],
   const char *strErrMsg 
); // C++ only
template <size_t size>
errno_t _wcserror_s(
   wchar_t (&buffer)[size],
   int errnum 
); // C++ only
template <size_t size>
errno_t __wcserror_s(
   wchar_t (&buffer)[size],
   const wchar_t *strErrMsg 
); // C++ only

Parameter

buffer
Puffer für die Fehlerzeichenfolge.
numberOfElements
Puffergröße.
errnum
Fehlernummer.
strErrMsg
Vom Benutzer angegebene Meldung.

Rückgabewert

Null, wenn erfolgreich, Fehlercode bei Fehler.

Fehlerbedingungen

buffer	numberOfElements	strErrMsg	Inhalt von buffer
NULL	any	any	nicht verfügbar
any	0	any	nicht geändert

Hinweise

Die strerror_s-Funktion ordnet errnum einer Fehlermeldungszeichenfolge zu und gibt die Zeichenfolge in buffer zurück. _strerror_s verwendet nicht die Fehlernummer, sondern den aktuellen Wert von errno, um die entsprechende Meldung zu bestimmen. Die Meldung wird allerdings weder von strerror_s noch _strerror_s gedruckt: Dazu muss eine Ausgabefunktion wie fprintf aufgerufen werden:

if (( _access( "datafile",2 )) == -1 )
{
   _strerror_s(buffer, 80);
   fprintf( stderr, buffer );
}

Wenn strErrMsgNULL ist, gibt _strerror_s eine Zeichenfolge in buffer zurück, die die Systemfehlermeldung zu dem letzten Bibliotheksaufruf enthält, der einen Fehler erzeugt hat. Die Fehlermeldungszeichenfolge wird durch das Zeilenumbruchzeichen ('\n') beendet. Wenn strErrMsg nicht gleich NULL ist, gibt _strerror_s eine Zeichenfolge in buffer zurück, die folgende Elemente (in der angegebenen Reihenfolge) enthält: die Zeichenfolgenmeldung, einen Doppelpunkt, ein Leerzeichen, die Systemfehlermeldung zu dem letzten Bibliotheksaufruf, einen Fehler erzeugt hat, und ein Zeilenumbruchzeichen. Die Zeichenfolgenmeldung darf höchstens 94 Zeichen lang sein.

Diese Funktionen schneiden die Fehlermeldung ab, wenn die Länge numberOfElements – 1 überschreitet. Die resultierende Zeichenfolge in buffer endet immer mit NULL.

Die tatsächliche Fehlernummer für _strerror_s wird in der Variablen errno gespeichert. Über die Variable _sys_errlist wird auf die Systemfehlermeldungen zugegriffen, die als Array von Meldungen nach Fehlernummern geordnet sind. _strerror_s greift auf die entsprechende Fehlermeldung zu, indem der errno-Wert als Index zur Variablen _sys_errlist verwendet wird. Der Wert der Variablen _sys_nerr wird als maximale Anzahl an Elementen im _sys_errlist-Array definiert. Um vollständige Ergebnisse zu erzeugen, rufen Sie umgehend _strerror_s auf, nachdem eine Bibliotheksroutine einen Fehler zurückgibt. Andernfalls können nachfolgende Aufrufe von strerror_s oder _strerror_s den errno-Wert überschreiben.

_wcserror_s und __wcserror_s sind Breitzeichenversionen von strerror_s und _strerror_s, verwendet.

Diese Funktionen überprüfen ihre Parameter. Wenn der Puffer NULL oder der Größenparameter 0 ist, wird der Handler für ungültige Parameter aufgerufen, wie in Parametervalidierung beschrieben. Wenn die weitere Ausführung zugelassen wird, gibt diese Funktion EINVAL zurück und setzt errno auf EINVAL.

_strerror_s, _wcserror_s, und __wcserror_s sind nicht Teil der ANSI-Definition, sondern zusätzliche Microsoft-Erweiterungen. Verwenden Sie sie nicht bei gewünschter Portabilität. Wenn Sie ANSI-Kompatibilität benötigen, verwenden Sie stattdessen strerror_s .

Die Verwendung dieser Funktionen in C++ wird durch Überladungen (als Vorlagen vorhanden) vereinfacht. Überladungen können automatisch die Pufferlänge ableiten, sodass kein Größenargument angegeben werden muss. Weitere Informationen finden Sie unter Sichere Vorlagenüberladungen.

Die Debugversionen dieser Funktionen füllen zunächst den Puffer mit "0xFD" auf. Mit _CrtSetDebugFillThreshold deaktivieren Sie dieses Verhalten.

Zuordnung generischer Textroutinen