wcsrtombs, wcsrtombs_s

 

C

Compiler-Unterstützung

Sprache

Header

Typunterstützung

Programm-Dienstprogramme

Unterstützung für variable Funktionsargumente

Fehlerbehandlung

Dynamische Speicherverwaltung

Bibliothek für Zeichenketten

Algorithmen

Numerik

Datums- und Zeitdienstprogramme

Ein-/Ausgabeunterstützung

Lokalisierungsunterstützung

Unterstützung für Nebenläufigkeit (C11)

Technische Spezifikationen

Symbolindex

 

Bibliothek für Zeichenketten

Null-terminierte Byte-Strings

Null-terminierte Multibyte-Strings

Null-terminierte breite Zeichenketten

 

Null-terminierte Multibyte-Strings

Funktionen
Breit-/Multibyte-Konvertierungen
mbsinit (C95)
mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11)   mbrtoc8 (C23) c8rtomb (C23) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen mbtowc wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
Typen
mbstate_t (C95) char8_t (C23)	char16_t (C11) char32_t (C11)
Makros
MB_LEN_MAX	MB_CUR_MAX

 

Definiert in Header <wchar.h>
	(1)
size_t wcsrtombs( char *dst, const wchar_t **src, size_t len, mbstate_t* ps );			(seit C95) (bis C99)
size_t wcsrtombs( char *restrict dst, const wchar_t **restrict src, size_t len,                   mbstate_t *restrict ps );			(seit C99)
errno_t wcsrtombs_s( size_t *restrict retval, char *restrict dst, rsize_t dstsz,                      const wchar_t **restrict src, rsize_t len,                      mbstate_t *restrict ps );		(2)	(seit C11)

1) Konvertiert eine Folge von Wide-Zeichen aus dem Array, dessen erstes Element auf *src zeigt, in seine schmale Multibyte-Darstellung, die im Konvertierungszustand beginnt, der durch *ps beschrieben wird. Wenn dst nicht null ist, werden die konvertierten Zeichen in aufeinanderfolgende Elemente des von dst zeigenden Char-Arrays geschrieben. Nicht mehr als len Bytes werden in das Ziel-Array geschrieben. Jedes Zeichen wird konvertiert, als ob es durch einen Aufruf von wcrtomb erfolgen würde. Die Konvertierung stoppt, wenn

• das Nullzeichen L'\0' konvertiert und gespeichert wurde. Die in diesem Fall gespeicherten Bytes sind die Unshift-Sequenz (falls erforderlich), gefolgt von '\0'. *src wird auf einen Nullzeiger gesetzt und *ps repräsentiert den anfänglichen Verschiebezustand.
• ein wchar_t gefunden wurde, das keinem gültigen Zeichen in der aktuellen C-Locale entspricht. *src wird so gesetzt, dass es auf das erste nicht konvertierte Wide-Zeichen zeigt.
• das nächste zu speichernde Multibyte-Zeichen len überschreiten würde. *src wird so gesetzt, dass es auf das erste nicht konvertierte Wide-Zeichen zeigt. Diese Bedingung wird nicht geprüft, wenn dst ein Nullzeiger ist.

2) Gleich wie (1), außer dass

• die Funktion gibt ihr Ergebnis als Out-Parameter retval zurück
• wenn die Konvertierung stoppt, ohne ein Nullzeichen zu schreiben, speichert die Funktion '\0' in das nächste Byte in dst, was dst[len] oder dst[dstsz] sein kann, je nachdem, was zuerst eintritt (was bedeutet, dass bis zu len+1/dstsz+1 Bytes geschrieben werden können). In diesem Fall wird möglicherweise keine Unshift-Sequenz vor dem abschließenden Nullzeichen geschrieben.
• die Funktion überschreibt das Ziel-Array vom abschließenden Nullzeichen bis dstsz
• Wenn src und dst sich überlappen, ist das Verhalten nicht spezifiziert.
• die folgenden Fehler werden zur Laufzeit erkannt und rufen die aktuell installierte Constraint-Handler-Funktion auf

• retval, ps, src oder *src ist ein Nullzeiger
• dstsz oder len ist größer als RSIZE_MAX (es sei denn, dst ist null)
• dstsz ist nicht null (es sei denn, dst ist null)
• len ist größer als dstsz und die Konvertierung stößt nicht auf einen Null- oder Kodierungsfehler im src-Array, bis dstsz erreicht ist (es sei denn, dst ist null)

Wie bei allen grenzgeprüften Funktionen ist wcsrtombs_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert wird und wenn der Benutzer __STDC_WANT_LIB_EXT1__ vor dem Einbinden von <wchar.h> auf die Ganzzahlkonstante 1 setzt.

Parameter

dst	-	Zeiger auf ein schmales Zeichen-Array, in dem die Multibyte-Zeichen gespeichert werden
src	-	Zeiger auf einen Zeiger auf das erste Element einer null-terminierten Wide-Zeichenkette
len	-	Anzahl der Bytes, die im von dst zeigenden Array verfügbar sind
ps	-	Zeiger auf das Konvertierungszustandsobjekt
dstsz	-	maximale Anzahl von Bytes, die geschrieben werden (Größe des dst-Arrays)
retval	-	Zeiger auf ein size_t-Objekt, in dem das Ergebnis gespeichert wird

Rückgabewert

1) Bei Erfolg gibt die Anzahl der Bytes zurück (einschließlich aller Umschaltsequenzen, aber ausschließlich des abschließenden '\0'), die in das Zeichen-Array geschrieben wurden, dessen erstes Element auf dst zeigt. Wenn dst ein Nullzeiger ist, gibt die Anzahl der Bytes zurück, die geschrieben worden wären. Bei einem Konvertierungsfehler (wenn ein ungültiges Wide-Zeichen gefunden wurde) wird (size_t)-1 zurückgegeben, EILSEQ in errno gespeichert und *ps in einem undefinierten Zustand belassen.

2) Gibt null bei Erfolg zurück (in diesem Fall wird die Anzahl der Bytes ohne abschließendes Nullzeichen, die in dst geschrieben wurden oder geschrieben worden wären, in *retval gespeichert), ungleich null bei einem Fehler. Bei einer Laufzeit-Constraint-Verletzung wird (size_t)-1 in *retval gespeichert (es sei denn, retval ist null) und dst[0] auf '\0' gesetzt (es sei denn, dst ist null oder dstmax ist null oder größer als RSIZE_MAX)

Beispiel

Führen Sie diesen Code aus

#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
 
void print_wide(const wchar_t* wstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    size_t len = 1 + wcsrtombs(NULL, &wstr, 0, &state);
    char mbstr[len];
    wcsrtombs(mbstr, &wstr, len, &state);
    printf("Multibyte string: %s\n", mbstr);
    printf("Length, including '\\0': %zu\n", len);
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_wide(L"z\u00df\u6c34\U0001f34c"); // or L"zß水🍌"
}

Ausgabe

Multibyte string: zß水🍌
Length, including '\0': 11

Referenzen

• C17-Standard (ISO/IEC 9899:2018)

• 7.29.6.4.2 Die Funktion wcsrtombs (S. 324-325)

• K.3.9.3.2.2 Die Funktion wcsrtombs_s (S. 471-472)

• C11-Standard (ISO/IEC 9899:2011)

• 7.29.6.4.2 Die Funktion wcsrtombs (S. 446)

• K.3.9.3.2.2 Die Funktion wcsrtombs_s (S. 649-651)

• C99-Standard (ISO/IEC 9899:1999)

• 7.24.6.4.2 Die Funktion wcsrtombs (S. 392)

Siehe auch

wcstombswcstombs_s (C11)	konvertiert einen Wide-String in einen schmalen Multibyte-Zeichenstring (Funktion)
wcrtombwcrtomb_s (C95)(C11)	konvertiert ein Wide-Zeichen in seine Multibyte-Darstellung, gegeben den Zustand (Funktion)
mbsrtowcsmbsrtowcs_s (C95)(C11)	konvertiert einen schmalen Multibyte-Zeichenstring in einen Wide-String, gegeben den Zustand (Funktion)
C++-Dokumentation für wcsrtombs