wcstombs, _wcstombs_l

Konvertiert eine Breitzeichensequenz in eine entsprechende Multibyte-Zeichensequenz. Sicherere Versionen dieser Funktionen sind verfügbar. Informationen dazu finden Sie unter wcstombs_s, _wcstombs_s_l.

Syntax

size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

Parameter

mbstr
Die Adresse einer Multibyte-Zeichensequenz.

wcstr
Adresse einer Breitzeichensequenz.

count
Die maximale Anzahl von Bytes, die in der Multibyte-Ausgabezeichenfolge gespeichert werden können.

locale
Das zu verwendende Gebietsschema.

Rückgabewert

Wenn wcstombs die Multibyte-Zeichenfolge erfolgreich konvertiert, wird die Anzahl der Bytes zurückgegeben, die in die Multibyte-Ausgabezeichenfolge geschrieben werden, mit Ausnahme des abschließenden Zeichens NULL (falls vorhanden). Wenn das mbstr-Argument NULL ist, gibt wcstombs die erforderliche Größe der Zielzeichenfolge in Bytes zurück. Wenn wcstombs ein breites Zeichen auftritt, kann es nicht in ein Multibyte-Zeichen konvertiert werden, wird -1 in Typ size_t umgewandelt und auf .errno EILSEQ

Hinweise

Die Funktion wcstombs konvertiert die Breitzeichenfolge, auf die von wcstr gezeigt wird, in die entsprechenden Multibytezeichen und speichert die Ergebnisse im mbstr-Array. Der Parameter count zeigt die maximale Anzahl von Bytes an, die in der Multibyte-Ausgabezeichenfolge gespeichert werden können (d.h. die Größe von mbstr). Im Allgemeinen ist nicht bekannt, wie viele Bytes beim Konvertieren einer Zeichenfolge mit breitem Zeichen erforderlich sind. Einige breite Zeichen erfordern nur ein einzelnes Byte in der Ausgabezeichenfolge. andere benötigen 2 Byte. Wenn in der Multibyte-Ausgabezeichenfolge für jedes breite Zeichen in der Eingabezeichenfolge (einschließlich des breiten Zeichens NULL) 2 Bytes vorhanden sind, wird das Ergebnis garantiert passen.

Ab Windows 10, Version 1803 (10.0.17134.0), unterstützt die universelle C-Runtime die Verwendung einer UTF-8-Codepage. Hiermit wcstombs(NULL, wcstr, 0) erhalten Sie die richtige Größe, die Sie für die Konvertierung benötigen, da davon ausgegangen wird, dass Sie zwei Bytes für jedes breite Zeichen benötigen, möglicherweise nicht ausreicht. Weitere Informationen zur UTF-8-Unterstützung finden Sie unter UTF-8-Unterstützung

Wenn wcstombs das Breitzeichen NULL (L'\0) entweder vor oder wann count auftritt, wird es in eine 8-Bit-0 konvertiert und angehalten. Daher ist die Multibyte-Zeichenzeichenfolge bei mbstr null-beendet, wenn wcstombs während der Konvertierung ein Breitzeichen NULL auftritt. Wenn die Sequenzen, auf die von wcstr und mbstr verwiesen wird, überlappen, ist das Verhalten von wcstombs nicht definiert.

Wenn das mbstr-Argument NULL ist, gibt wcstombs die erforderliche Größe der Zielzeichenfolge in Bytes zurück.

wcstombs überprüft die eigenen Parameter. Wenn wcstr dies größer INT_MAXals ist count NULL, ruft diese Funktion den ungültigen Parameterhandler auf, wie in der Parameterüberprüfung beschrieben. Wenn die weitere Ausführung zugelassen wird, legt die Funktion errno auf EINVAL fest und gibt -1 zurück.

wcstombs verwendet das aktuelle Gebietsschema für jedes Verhalten, das vom Gebietsschema abhängig ist; _wcstombs_l ist identisch, nur dass sie stattdessen das übergebene Gebietsschema verwendet. Weitere Informationen finden Sie unter Locale.

In C++ haben diese Funktionen Vorlagenüberladungen, mit denen die neueren, sicheren Entsprechungen dieser Funktionen aufgerufen werden. 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.

Anforderungen

Weitere Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Beispiel

Dieses Programm stellt das Verhalten der Funktion wcstombs dar.

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t  count;
    char    *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t *pWCBuffer = L"Hello, world.";

    printf("Convert wide-character string:\n" );

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}

Convert wide-character string:
   Characters converted: 13
    Multibyte character: Hello, world.

Siehe auch

Datenkonvertierung
Gebietsschema
_mbclen, mblen_mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb, _wctomb_l
WideCharToMultiByte