Freigeben über

mbstowcs_s, _mbstowcs_s_l

  • Artikel

Konvertiert eine Multibyte-Zeichensequenz in eine entsprechende Breitzeichensequenz. Versionen von mbstowcs, _mbstowcs_l mit Sicherheitsverbesserungen, wie in den Sicherheitsfeatures in der CRT beschrieben.

Syntax

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

Parameter

pReturnValue
Die Anzahl von konvertierten Zeichen.

wcstr
Pufferadresse zum Speichern der resultierenden konvertierten Breitzeichenfolge.

sizeInWords
Größe des Puffers wcstr in Worten.

mbstr
Adresse einer Multibyte-Zeichensequenz.

count
Die maximale Anzahl von breiten Zeichen, die wcstr im Puffer gespeichert werden sollen, nicht einschließlich des endenden Nullwerts oder _TRUNCATE.

locale
Das zu verwendende Gebietsschema.

Rückgabewert

Null, wenn erfolgreich, Fehlercode bei Fehler.

Fehlerbedingung Rückgabewert und errno
wcstr ist NULL und sizeInWords> 0 EINVAL
mbstr ist NULL. EINVAL
Der Zielpuffer ist für die konvertierte Zeichenfolge zu klein (es sei denn, count ist gleich _TRUNCATE; siehe Abschnitt „Hinweise“) ERANGE
wcstr ist nicht NULL und sizeInWords == 0 EINVAL

Wenn eine dieser Bedingungen auftritt, wird die ausnahme für ungültige Parameter aufgerufen, wie in der Parameterüberprüfung beschrieben. Wenn die Ausführung fortgesetzt werden kann, gibt die Funktion einen Fehlercode zurück und legt errno wie in der Tabelle angegeben fest.

Hinweise

Die mbstowcs_s-Funktion konvertiert eine Zeichenfolge mit Multibytezeichen, auf die von mbstr verwiesen wird, in im Puffer gespeicherte Breitzeichen, auf die von wcstr verwiesen wird. Die Konvertierung wird für jedes Zeichen fortgesetzt, bis eine der folgenden Bedingungen eintritt:

  • Ein Multibyte-Nullzeichen wird erkannt.

  • Ein ungültiges Multibytezeichen wird erkannt.

  • Die Anzahl der Breitzeichen, die im wcstr-Puffer gespeichert sind, ist gleich count.

Die Zielzeichenfolge wird immer null beendet (auch wenn ein Fehler auftritt).

Wenn count es sich um den speziellen Wert _TRUNCATEhandelt, mbstowcs_s wird so viel der Zeichenfolge konvertiert, wie er in den Zielpuffer passt, während der Raum für einen Null-Endator noch nicht verfügbar ist.

Wenn mbstowcs_s die Quellzeichenfolge erfolgreich konvertiert wird, wird die Größe in breite Zeichen der konvertierten Zeichenfolge, einschließlich des Null-Terminators, in *pReturnValue (angegeben pReturnValue ist nicht NULL) eingefügt. Die Größe wird auch dann berechnet, wenn das wcstr Argument lautet NULL, und bietet eine Möglichkeit, die erforderliche Puffergröße zu bestimmen. Wenn wcstr dies der Wert ist NULL, count wird ignoriert und sizeInWords muss 0 sein.

Wenn mbstowcs_s ein ungültiges Multibytezeichen erkennt, schreibt es 0 in *pReturnValue, legt den Zielpuffer auf eine leere Zeichenfolge fest, legt errno auf EILSEQ fest und gibt dann EILSEQ zurück.

Wenn die Sequenzen, auf die von mbstr und wcstr verwiesen wird, überlappen, ist das Verhalten von mbstowcs_s nicht definiert.

Wichtig

Stellen Sie sicher, dass wcstr und mbstr nicht überlappen und dass count die Anzahl zu konvertierenderMultibytezeichen korrekt darstellt.

mbstowcs_s verwendet das aktuelle Gebietsschema für jedes Verhalten, das vom Gebietsschema abhängig ist; _mbstowcs_s_l ist identisch, nur dass sie stattdessen das übergebene Gebietsschema verwendet. Weitere Informationen finden Sie unter Locale.

In C++ wird die Verwendung dieser Funktionen durch Vorlagenüberladungen vereinfacht; die Überladungen können automatisch Rückschlüsse auf die Pufferlänge ziehen (wodurch kein Größenargument mehr angegeben werden muss), und sie können automatisch die älteren, nicht sicheren Funktionen durch ihre neueren, sicheren Entsprechungen ersetzen. Weitere Informationen finden Sie unter Secure Template Overloads.

Standardmäßig gilt der globale Zustand dieser Funktion für die Anwendung. Wie Sie dieses Verhalten ändern, erfahren Sie unter Globaler Status in der CRT.

Anforderungen

Routine Erforderlicher Header
mbstowcs_s <stdlib.h>
_mbstowcs_s_l <stdlib.h>

Weitere Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Siehe auch

Datenkonvertierung
Gebietsschema
MultiByteToWideChar
Interpretation von Multibytezeichensequenzen
_mbclen, mblen_mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l