`mbsrtowcs_s`

Artikel
10/12/2023

Konvertieren einer Zeichenfolge mit Multibytezeichen im aktuellen Gebietsschema in die entsprechende Zeichenfolge mit Breitzeichen. Eine Version mit mbsrtowcs Sicherheitsverbesserungen, wie in den Sicherheitsfeatures in der CRT beschrieben.

Syntax

errno_t mbsrtowcs_s(
   size_t * pReturnValue,
   wchar_t * wcstr,
   size_t sizeInWords,
   const char ** mbstr,
   size_t count,
   mbstate_t * mbstate
);
template <size_t size>
errno_t mbsrtowcs_s(
   size_t * pReturnValue,
   wchar_t (&wcstr)[size],
   const char ** mbstr,
   size_t count,
   mbstate_t * mbstate
); // C++ only

Parameter

pReturnValue
Die Anzahl von konvertierten Zeichen.

wcstr
Pufferadresse zum Speichern der resultierenden konvertierten Zeichenfolge mit Breitzeichen.

sizeInWords
Die Größe von wcstr in Wörtern (Breitzeichen).

mbstr
Indirekter Zeiger auf den Speicherort der Multibyte-Zeichenfolge, die konvertiert werden soll.

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

mbstate
Ein Zeiger auf ein mbstate_t-Konvertierungszustandsobjekt. Wenn dieser Wert ein NULL-Zeiger ist, wird ein statisches internes Konvertierungszustandsobjekt verwendet. Da das interne mbstate_t Objekt nicht threadsicher ist, wird empfohlen, immer Ihren eigenen mbstate Parameter zu übergeben.

Rückgabewert

Null, wenn die Konvertierung erfolgreich ist, oder ein Fehlercode bei einem Fehler.

Fehlerbedingung	Rückgabewert und `errno`
`wcstr` ist ein Nullzeiger und `sizeInWords`> 0	`EINVAL`
`mbstr` ist ein NULL-Zeiger	`EINVAL`
Die Zeichenfolge, auf `mbstr` die indirekt verwiesen wird, enthält eine Multibyte-Sequenz, die für das aktuelle Gebietsschema nicht gültig ist.	`EILSEQ`
Der Zielpuffer ist zu klein für die konvertierte Zeichenfolge enthalten (es sei denn, `count` ist `_TRUNCATE`; weitere Informationen finden Sie unter "Hinweise")	`ERANGE`

Wenn eine dieser Bedingungen auftritt, wird die ungültige Parameter-Ausnahme 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 mbsrtowcs_s-Funktion konvertiert eine Zeichenfolge von Multibytezeichen, auf die indirekt von mbstr gezeigt wird, in im Puffer gespeicherte Breitzeichen, auf die von wcstr gezeigt wird, und verwendet dafür den in mbstate enthaltenen Konvertierungszustand. 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 wcstr wird immer null beendet, auch wenn ein Fehler auftritt, es sei denn, es handelt sich um wcstr einen Nullzeiger.

Wenn count es sich um den speziellen Wert _TRUNCATEhandelt, mbsrtowcs_s wird so viel von der Zeichenfolge konvertiert, wie sie in den Zielpuffer passt, während der Platz für einen Null-Endator bleibt.

Wenn mbsrtowcs_s die Quellzeichenfolge erfolgreich konvertiert wird, wird die Größe in breite Zeichen der konvertierten Zeichenfolge und der NULL-Terminator eingefügt *pReturnValue, vorausgesetzt pReturnValue , es handelt sich nicht um einen Nullzeiger. Die Größe wird auch dann berechnet, wenn es sich bei dem wcstr Argument um einen Nullzeiger handelt, mit dem Sie die erforderliche Puffergröße bestimmen können. Wenn wcstr es sich um einen Nullzeiger handelt, count wird dieser ignoriert.

Wenn wcstr es sich nicht um einen Nullzeiger handelt, wird dem Zeigerobjekt, auf das mbstr verwiesen wird, ein Nullzeiger zugewiesen, wenn die Konvertierung beendet wurde, weil ein endendes Nullzeichen erreicht wurde. Andernfalls wird die Adresse direkt über das letzte konvertierte Multibyte-Zeichen zugewiesen. Er ermöglicht es einem nachfolgenden Funktionsaufruf, die Konvertierung neu zu starten, in der dieser Aufruf beendet wurde.

Wenn mbstate ein NULL-Zeiger ist, wird das bibliotheksinterne statische mbstate_t-Konvertierungszustandobjekt verwendet. Da dieses interne statische Objekt nicht threadsicher ist, empfehlen wir, dass Sie Ihren eigenen mbstate Wert übergeben.

Wenn mbsrtowcs_s ein multibyte-Zeichen gefunden wird, das im aktuellen Gebietsschema nicht gültig ist, legt es -1 in *pReturnValue, legt den Zielpuffer wcstr auf eine leere Zeichenfolge fest, legt errno sie auf EILSEQund gibt diese zurück EILSEQ.

Wenn die Sequenzen, auf die von mbstr und wcstr verwiesen wird, überlappen, ist das Verhalten von mbsrtowcs_s nicht definiert. mbsrtowcs_s wird von der LC_TYPE Kategorie des aktuellen Gebietsschemas beeinflusst.

Wichtig

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

Die mbsrtowcs_s Funktion unterscheidet sich von mbstowcs_sder _mbstowcs_s_l Neustartbarkeit. Der Konvertierungszustand wird für nachfolgende Aufrufe der gleichen oder anderer Funktionen, die neu gestartet werden können, in mbstate gespeichert. Wenn sowohl Funktionen, die neu gestartet werden können, als auch Funktionen, die nicht neu gestartet werden könnnen, verwendet werden, sind die Ergebnisse undefiniert. Eine Anwendung sollte mbsrlen z. B. anstelle von mbslen, wenn anstelle eines mbstowcs_snachfolgenden Aufrufs mbsrtowcs_s eine Anwendung verwendet wird.

In C++ wird die Verwendung dieser Funktion durch Vorlagenüberladungen vereinfacht; Die Überladungen können die Pufferlänge automatisch ableiten (ohne die Anforderung, ein Größenargument anzugeben) und sie können ältere, nicht sichere Funktionen automatisch durch die 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.

Ausnahmen

Die mbsrtowcs_s Funktion ist multithreadsicher, wenn keine Funktion im aktuellen Thread aufruft setlocale , solange diese Funktion ausgeführt wird und das mbstate Argument kein Nullzeiger ist.

Anforderungen

Routine	Erforderlicher Header
`mbsrtowcs_s`	<wchar.h>

Siehe auch

Datenkonvertierung
Gebietsschema
Interpretation von Multibytezeichensequenzen
mbrtowc
mbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_l
mbsinit

Freigeben über