mbsrtowcs

Konvertiert eine Zeichenfolge mit Multibytezeichen im aktuellen Gebietsschema in die entsprechende Zeichenfolge mit Breitzeichen, mit der Möglichkeit des Neustarts in der Mitte eines Multibytezeichens. Eine sicherere Version dieser Funktion ist verfügbar; siehe mbsrtowcs_s.

Syntax

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

Parameter

wcstr
Adresse zum Speichern der resultierenden konvertierten Zeichenfolge mit Breitzeichen.

mbstr
Indirekter Zeiger auf den Speicherort der zu konvertierenden Zeichenfolge mit Multibytezeichen.

count
Die maximale Anzahl von Zeichen (nicht Bytes), die konvertiert und in wcstr gespeichert werden sollen.

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

Gibt die Anzahl der Zeichen zurück, die erfolgreich konvertiert wurden, nicht einschließlich des abschließenden Zeichens NULL, sofern vorhanden. Gibt (size_t)(-1) zurück, wenn ein Fehler aufgetreten ist, und legt diesen errno wert auf EILSEQ.

Hinweise

Die mbsrtowcs-Funktion konvertiert eine Zeichenfolge mit Multibytezeichen, auf die indirekt von mbstr verwiesen wird, in im Puffer gespeicherte Breitzeichen, auf die von wcstr verwiesen wird, und verwendet dafür den in mbstate enthaltenen Konvertierungszustand. Die Konvertierung wird für jedes Zeichen fortgesetzt, bis entweder ein beendetes Null-Multibyte-Zeichen gefunden wird, eine Multibyte-Sequenz, die keinem gültigen Zeichen im aktuellen Gebietsschema entspricht, oder bis count Zeichen konvertiert wurden. Wenn mbsrtowcs das Multibytezeichen NULL ('\0') erkennt, entweder vor oder bei count, wird es in ein abschließendes 16-Bit-Zeichen NULL konvertiert und beendet.

Folglich endet die Breitzeichen-Zeichenfolge bei wcstr nur dann auf NULL, wenn mbsrtowcs während der Konvertierung ein Multibytezeichen NULL findet. Wenn die Sequenzen, auf die von mbstr und wcstr verwiesen wird, überlappen, ist das Verhalten von mbsrtowcs nicht definiert. mbsrtowcs wird von der LC_TYPE Kategorie des aktuellen Gebietsschemas beeinflusst.

Die mbsrtowcs Funktion unterscheidet sich von mbstowcsder _mbstowcs_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 mbstowcsnachfolgenden Aufrufs mbsrtowcs eine Anwendung verwendet wird.

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 das wcstr Argument ein NULL-Zeiger ist, wird das count Argument ignoriert und mbsrtowcs gibt die erforderliche Größe in breiten Zeichen für die Zielzeichenfolge zurück. Wenn mbstate ein NULL-Zeiger ist, verwendet die Funktion ein nicht threadsicheres statisches internes mbstate_t-Konvertierungszustandsobjekt. Wenn die Zeichenfolge mbstr keine entsprechende Multibyte-Zeichendarstellung hat, wird ein -1 zurückgegeben und errno auf EILSEQ.

Wenn mbstr ein NULL-Zeiger ist, wird der Handler für ungültige Parameter aufgerufen, wie in Parameter Validation (Parameterüberprüfung) beschrieben. Wenn die weitere Ausführung zugelassen wird, setzt diese Funktion errno auf EINVAL und gibt "-1" zurück.

In C++ hat diese Funktion eine Vorlagenüberladung, mit der die neuere, sichere Entsprechung dieser Funktion aufgerufen wird. 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 Funktion ist multithreadsicher, solange keine Funktion im aktuellen Thread aufruft setlocale , solange diese Funktion ausgeführt wird und das mbstate Argument kein Nullzeiger ist.

Anforderungen

Siehe auch

Datenkonvertierung
Gebietsschema
Interpretation von Multibytezeichensequenzen
mbrtowc
mbtowc, _mbtowc_l
mbstowcs, _mbstowcs_l
mbsinit