mbstowcs_s, _mbstowcs_s_l

Artikel
02/26/2013

Konvertiert eine Folge von multibyte-Zeichen in einer entsprechenden Bytefolge Breitzeichen.Versionen von mbstowcs, _mbstowcs_l mit Sicherheitsverbesserungen wie in beschrieben Sicherheitsfeatures im CRT.

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

[out] pReturnValue
Die Anzahl der Zeichen konvertiert.
[out] wcstr
Adresse des Puffers für die resultierende konvertiert Breitzeichen-Zeichenfolge.
[in] sizeInWords
Die Größe der wcstr Puffer in Worten.
[in]mbstr
Die Adresse einer Sequenz von Null beendet Multibytezeichen.
[in] count
Die maximale Anzahl der Breitzeichen in Speichern der wcstr Puffer, einschließlich der nicht das abschließende Nullzeichen oder _TRUNCATE.
[in] locale
Das Gebietsschema verwenden.

Rückgabewert

NULL bei Erfolg, Fehler-Code bei einem Fehler.

Fehlerbedingung	Rückgabewert underrno
wcstris NULL and sizeInWords > 0	EINVAL
mbstr ist NULL	EINVAL
Der Zielpuffer ist zu klein, um die konvertierte Zeichenfolge enthalten (es sei denn, count ist _TRUNCATE; Siehe Hinweise weiter unten)	ERANGE
wcstris not NULL and sizeInWords == 0	EINVAL

Wenn eine dieser Bedingungen auftritt, wird die Ausnahme Ungültiger Parameter aufgerufen, wie beschrieben unter Parametervalidierung .Wenn die Ausführung zulässig ist, um den Vorgang fortzusetzen, gibt die Funktion einen Fehlercode zurück und legt errno in der Tabelle angegeben.

Hinweise

Die mbstowcs_s -Funktion konvertiert eine Zeichenfolge multibyte-Zeichen, auf die mbstr in Breitzeichen, die in den Puffer, auf den gespeicherten wcstr.Die Konvertierung wird für jedes Zeichen fortgesetzt, bis eine der folgenden Bedingungen erfüllt ist:

Ein Null-Multibytezeichen ist aufgetreten.
Ein ungültiges Mehrbyte-Zeichen ist aufgetreten.
Die Anzahl der Breitzeichen in gespeichert die wcstr Puffer ist gleich count.

Der Zielzeichenfolge ist immer Null-terminierte (sogar im Falle eines Fehlers).

Wenn count ist der spezielle Wert _TRUNCATE, dann mbstowcs_s konvertiert die Zeichenfolge als wird in den Zielpuffer passen, während immer noch Platz für einen null-Terminator.

Wenn mbstowcs_s die Quellzeichenfolge erfolgreich konvertiert wird die Größe in Breitzeichen der konvertierten Zeichenfolge, einschließlich der null-Terminator in *pReturnValue (bereitgestellten pReturnValue ist nicht NULL).Dies tritt auf, selbst wenn die wcstr -Argument ist NULL und bietet eine Möglichkeit zum Bestimmen der erforderlichen Puffergröße.Note that if wcstr is NULL, count is ignored, and sizeInWords must be 0.

Wenn mbstowcs_s findet ein ungültiges Mehrbyte-Zeichen, es setzt 0 in *pReturnValue, den Zielpuffer auf eine leere Zeichenfolge festgelegt, legt errno , EILSEQ, und gibt EILSEQ.

Wenn die Sequenzen von verwies mbstr und wcstr überlappen, das Verhalten der mbstowcs_s ist nicht definiert.

Sicherheitshinweis
Stellen Sie sicher, dass wcstr und mbstr nicht überlappen, und dass count korrekt reflektiert die Anzahl der multibyte-Zeichen konvertieren.

mbstowcs_sverwendet das aktuelle Gebietsschema für jedes Gebietsschema abhängigen Verhalten; _mbstowcs_s_list identisch, außer dass es das Gebietsschema übergebene stattdessen verwendet.Weitere Informationen finden Sie unter Gebietsschema.

In C++ wird die Verwendung dieser Funktionen von Vorlagenüberladungen vereinfacht; Die Überladungen können Pufferlänge automatisch ableiten (die überflüssig ein Größe-Argument angeben) und sie können ältere, nicht sichere Funktionen automatisch mit ihren Gegenstücken neueren und sicheren ersetzen.Weitere Informationen finden Sie unter Speichern Sie Vorlagen-Überladungen.