mbstowcs_s, _mbstowcs_s_l

Artikel
06/09/2015

Konvertiert eine Sequenz von Mehrbytezeichen zu der entsprechenden Reihenfolge von Breitzeichen. Versionen von mbstowcs, _mbstowcs_l mit werden, wie in Sicherheitsfunktionen in der CRT beschrieben.

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 Zurückhalten konvertierte Zeichenfolge mit Breitzeichen.
[in] sizeInWords
Die Größe des Puffers wcstr mit den Wörtern.
[in]mbstr
Die Adresse einer Sequenz NULL beendete Mehrbytezeichen.
[in] count
Die maximale Anzahl im wcstr Puffer, ohne das abschließende NULL-Zeichen zu lagern den Breitzeichen, oder _TRUNCATE.
[in] locale
Das zu verwendende Gebietsschema.

Rückgabewert

Null, wenn erfolgreich, Fehlercode bei Fehler.

Fehlerstatus	Rückgabewert und errno
wcstr ist NULL und sizeInWords > 0	EINVAL
mbstr ist NULL	EINVAL
Der Zielpuffer ist zu klein, die konvertierte Zeichenfolge zu enthalten (es sei denn, count ; _TRUNCATE ist siehe Hinweise) unten	ERANGE
wcstr ist nicht NULL und sizeInWords == 0	EINVAL

Wenn diese Bedingungen auftritt, wird die ungültige Parameterausnahme aufgerufen, wie in Parametervalidierung beschrieben. Wenn die Ausführung zulässig ist, um fortzufahren, gibt die Funktion einen Fehlercode zurück und legt errno fest, wie in der Tabelle angegeben.

Hinweise

Die mbstowcs_s-Funktion konvertiert eine Zeichenfolge aus den Mehrbytezeichen, auf die mbstr der Breitzeichen dargestellt werden, die im Puffer gespeichert werden, auf den durch wcstr gezeigt wird. Die Konvertierung wird für jedes Zeichen fortgesetzt, bis eine dieser Bedingungen erfüllt ist:

Ein Mehrbytenull-zeichen auftritt
Ein NULL-Makro Mehrbytezeichen auftritt
Die Anzahl der Breitzeichen, die im wcstr Puffer gespeichert werden, entspricht count.

Die Zielzeichenfolge ist immer auf NULL enden (selbst im Falle eines Fehlers.)

Wenn count den speziellen Wert _TRUNCATE ist, konvertiert mbstowcs_s so weit der Zeichenfolge, wie in den Zielpuffer passt, wobei Platz für einen Nullterminator weiterhin beibehalten.

Wenn mbstowcs_s erfolgreich die Quellzeichenfolge konvertiert, wird die Größe in Breitzeichen der konvertierten Zeichenfolge, einschließlich das NULL-Zeichen, in *(ein pReturnValue bereit gestelltes pReturnValue nicht NULL ist). Dies tritt auf, wcstr, wenn das Argument NULL und bietet eine Möglichkeit, die erforderliche Puffergröße zu ermitteln. Beachten Sie, dass, wenn wcstrNULL ist, die count ignoriert wird, und sizeInWords muss 0 sein.

Wenn mbstowcs_s ein ungültiges Mehrbytezeichen stößt, gibt es 0 in *pReturnValue, legt den Zielpuffer auf eine leere Zeichenfolge fest, wird errno auf EILSEQ festgelegt und EILSEQ zurückgegeben.

Wenn die Sequenzen, die von mbstr und wcstr Überlappung, das Verhalten von mbstowcs_s dargestellt werden, die definiert.

Sicherheitshinweis
Stellen Sie sicher, dass wcstr und mbstr nicht überschneiden und dass count richtig die Anzahl Mehrbytezeichen an verschiedenen mitgeteilt.

mbstowcs_s verwendet das aktuelle Gebietsschema jedes gebietsschemaabhängigen Verhalten; _mbstowcs_s_l ist identisch, es verwendet das Gebietsschema, das ein- stattdessen übergeben wird. 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 Sichere Vorlagenüberladungen.