wcstombs, wcstombs_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 im Header <stdlib.h>
	(1)
size_t wcstombs( char          *dst, const wchar_t          *src, size_t len );			(bis C99)
size_t wcstombs( char *restrict dst, const wchar_t *restrict src, size_t len );			(seit C99)
errno_t wcstombs_s( size_t *restrict retval, char *restrict dst, rsize_t dstsz,                     const wchar_t *restrict src, rsize_t len );		(2)	(seit C11)

1) Konvertiert eine Sequenz von Wide-Zeichen aus dem Array, auf dessen erstes Element src zeigt, in seine schmale Multibyte-Repräsentation, die im initialen Shift-Zustand beginnt. Konvertierte Zeichen werden in den aufeinanderfolgenden Elementen des Char-Arrays gespeichert, auf das dst zeigt. Es werden nicht mehr als len Bytes in das Ziel-Array geschrieben.

Jedes Zeichen wird konvertiert, als ob es durch einen Aufruf von wctomb konvertiert würde, mit der Ausnahme, dass der Konvertierungszustand von wctomb unberührt bleibt. 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',

* ein wchar_t gefunden wurde, das keinem gültigen Zeichen in der aktuellen C-Locale entspricht.

* das nächste zu speichernde Multibyte-Zeichen len überschreiten würde.

Wenn src und dst sich überlappen, ist das Verhalten undefiniert.

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

* Konvertierung erfolgt wie durch wcrtomb, nicht durch wctomb

* die Funktion gibt ihr Ergebnis als Ausgabeparameter retval zurück

* wenn die Konvertierung stoppt, ohne ein Nullzeichen zu schreiben, speichert die Funktion '\0' im nächsten Byte in dst, das entweder dst[len] oder dst[dstsz] sein kann, je nachdem, welches zuerst eintritt (was bedeutet, dass bis zu len+1/dstsz+1 Bytes insgesamt geschrieben werden können). In diesem Fall wird möglicherweise keine Unshift-Sequenz vor dem terminierenden Nullzeichen geschrieben.

* wenn dst ein Nullzeiger ist, wird die Anzahl der Bytes, die produziert würden, in *retval gespeichert

* die Funktion überschreibt das Ziel-Array vom terminierenden Nullzeichen bis dstsz

* Wenn src und dst sich überlappen, ist das Verhalten undefiniert.

* die folgenden Fehler werden zur Laufzeit erkannt und rufen die aktuell installierte Constraint-Handler-Funktion auf

• retval 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 wcstombs_s nur dann garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert wird und wenn der Benutzer __STDC_WANT_LIB_EXT1__ vor dem Einbinden von <stdlib.h> auf die Ganzzahlkonstante 1 setzt.

Hinweise

In den meisten Implementierungen aktualisiert wcstombs ein globales statisches Objekt vom Typ mbstate_t, während es den String verarbeitet, und kann nicht gleichzeitig von zwei Threads aufgerufen werden. In solchen Fällen sollten wcsrtombs oder wcstombs_s verwendet werden.

POSIX spezifiziert eine gängige Erweiterung: wenn dst ein Nullzeiger ist, gibt diese Funktion die Anzahl der Bytes zurück, die nach Konvertierung in dst geschrieben würden. Ein ähnliches Verhalten ist Standard für wcsrtombs und wcstombs_s.

Parameter

dst	-	Zeiger auf das schmale Zeichenarray, in dem das Multibyte-Zeichen gespeichert wird
src	-	Zeiger auf das erste Element eines nullterminierten Wide-Strings, der konvertiert werden soll
len	-	Anzahl der Bytes, die im von dst zeigenden Array verfügbar sind
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 wird die Anzahl der Bytes (einschließlich aller Shift-Sequenzen, aber ausschließlich des terminierenden '\0') zurückgegeben, die in das Zeichen-Array geschrieben wurden, auf dessen erstes Element dst zeigt. Bei einem Konvertierungsfehler (wenn ein ungültiges Wide-Zeichen angetroffen wurde) wird (size_t)-1 zurückgegeben.

2) Gibt Null bei Erfolg zurück (in diesem Fall wird die Anzahl der Bytes ohne das terminierende Nullzeichen, die in dst geschrieben wurden oder würden, in *retval gespeichert), ungleich Null bei einem Fehler. Im Falle einer Laufzeit-Constraint-Verletzung wird (size_t)-1 in *retval gespeichert (es sei denn, retval ist null) und dst[0] wird 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 <stdlib.h>
#include <locale.h>
 
int main(void)
{
    // 4 wide characters
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // they occupy 10 bytes in UTF-8
    char dst[11];
 
    setlocale(LC_ALL, "en_US.utf8");
    printf("wide-character string: '%ls'\n",src);
    for (size_t ndx=0; ndx < sizeof src/sizeof src[0]; ++ndx)
        printf("   src[%2zu] = %#8x\n", ndx, src[ndx]);
 
    int rtn_val = wcstombs(dst, src, sizeof dst);
    printf("rtn_val = %d\n", rtn_val);
    if (rtn_val > 0)
        printf("multibyte string:  '%s'\n",dst);
    for (size_t ndx=0; ndx<sizeof dst; ++ndx)
        printf("   dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]);
}

Ausgabe

wide-character string: 'zß水🍌'
   src[ 0] =     0x7a
   src[ 1] =     0xdf
   src[ 2] =   0x6c34
   src[ 3] =  0x1f34c
   src[ 4] =        0
rtn_val = 10
multibyte string:  'zß水🍌'
   dst[ 0] = 0x7a
   dst[ 1] = 0xc3
   dst[ 2] = 0x9f
   dst[ 3] = 0xe6
   dst[ 4] = 0xb0
   dst[ 5] = 0xb4
   dst[ 6] = 0xf0
   dst[ 7] = 0x9f
   dst[ 8] = 0x8d
   dst[ 9] = 0x8c
   dst[10] =  0

Referenzen

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

• 7.22.8.2 Die Funktion wcstombs (S. 360)

• K.3.6.5.2 Die Funktion wcstombs_s (S. 612-614)

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

• 7.20.8.2 Die Funktion wcstombs (S. 324)

• C89/C90-Standard (ISO/IEC 9899:1990)

• 4.10.8.2 Die Funktion wcstombs

Siehe auch

wcsrtombswcsrtombs_s (C95)(C11)	konvertiert einen Wide-String in einen schmalen Multibyte-Zeichenstring, gegeben den Zustand (Funktion)
mbstowcsmbstowcs_s (C11)	konvertiert einen schmalen Multibyte-Zeichenstring in einen Wide-String (Funktion)
C++ Dokumentation für wcstombs