mbsrtowcs_s

Artikel
06/09/2015

Konvertieren einer Zeichenfolge mit Multibytezeichen im aktuellen Gebietsschema in die entsprechende Zeichenfolge mit Breitzeichen. Eine Version von mbsrtowcs enthält Sicherheitserweiterungen wie unter Sicherheitsfunktionen in der CRT beschrieben.

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

[out] pReturnValue
Die Anzahl von konvertierten Zeichen.
[out] wcstr
Pufferadresse zum Speichern der resultierenden konvertierten Zeichenfolge mit Breitzeichen.
[out] sizeInWords
Die Größe von wcstr in Wörtern (Breitzeichen).
[in, out] mbstr
Indirekter Zeiger auf den Speicherort der Multibyte-Zeichenfolge, die konvertiert werden soll.
[in] count
Die maximale Anzahl von Breitzeichen, die im wcstr-Puffer gespeichert werden können, wobei das abschließende Nullzeichen nicht eingeschlossen ist, oder _TRUNCATE.
[in, out] 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 NULL-Zeiger und sizeInWords > 0	EINVAL
mbstr ist ein NULL-Zeiger	EINVAL
Die Zeichenfolge, auf die indirekt von mbstr gezeigt wird, enthält eine Multibyte-Sequenz, die für das aktuelle Gebietsschema ungü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 Ausnahme für ungültige Parameter aufgerufen, wie in Parametervalidierung 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 endet immer mit NULL, selbst bei einem Fehler, es sei denn wcstr ist ein NULL-Zeiger.

Wenn count der spezielle Wert _TRUNCATE ist, konvertiert mbsrtowcs_s einen so großen Teil der Zeichenfolge wie in den Zielpuffer passt, während weiterhin Platz für einen NULL-Terminator bleibt.

Wenn mbsrtowcs_s die Quellzeichenfolge erfolgreich konvertiert, wird die Größe der konvertierten Zeichenfolge in Breitzeichen und der NULL-Terminator in *pReturnValue geschrieben, vorausgesetzt, pReturnValue ist kein NULL-Zeiger. Dieser Fehler tritt auf, selbst wenn das wcstr-Argument ein NULL-Zeiger ist und Sie die erforderliche Puffergröße bestimmen können. Beachten Sie, dass wenn wcstr ein NULL-Zeiger ist, wird count ignoriert.

Wenn wcstr kein NULL-Zeiger ist, wird das Zeigerobjekt, auf das von mbstr verwiesen wird, einem NULL-Zeiger zugewiesen, wenn die Konvertierung beendet wird, da ein abschließendes Nullzeichen erreicht wurde. Andernfalls wird es ggf. der Adresse unmittelbar nach dem letzten konvertierten Multibytezeichen zugewiesen. Auf diese Weise kann ein nachfolgender Funktionsaufruf die Konvertierung an der Stelle neu starten, an der der 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, wird empfohlen, immer Ihren eigenen mbstate-Wert zu übergeben.

Wenn mbsrtowcs_s ein Multibytezeichen erkennt, das im aktuellen Gebietsschema ungültig ist, wird -1 in *pReturnValue geschrieben, der wcstr-Zielpuffer auf eine leere Zeichenfolge festgelegt, errno auf EILSEQ festgelegt und EILSEQ zurückgegeben.

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

Sicherheitshinweis
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_s, _mbstowcs_s_l anhand ihrer Möglichkeit, neu gestartet zu werden. 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 beispielsweise mbsrlen anstelle von mbslen verwenden, wenn ein nachfolgender Aufruf von mbsrtowcs_s anstelle von mbstowcs_s. verwendet wird.

In C++ wird die Verwendung dieser Funktion 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.

Ausnahmen

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