wcrtomb_s

Konvertieren von Breitzeichen in die Multibyte-Zeichendarstellung. Eine Version mit wcrtomb Sicherheitsverbesserungen, wie in den Sicherheitsfeatures in der CRT beschrieben.

Syntax

errno_t wcrtomb_s(
   size_t *pReturnValue,
   char *mbchar,
   size_t sizeOfmbchar,
   wchar_t *wchar,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcrtomb_s(
   size_t *pReturnValue,
   char (&mbchar)[size],
   wchar_t *wchar,
   mbstate_t *mbstate
); // C++ only

Parameter

pReturnValue
Gibt die Anzahl geschriebener Bytes oder „-1“ bei einem Fehler zurück.

mbchar
Das resultierende in Multibyte konvertierte Zeichen.

sizeOfmbchar
Die Größe der Variablen mbchar in Bytes.

wchar
Ein zu konvertierendes Breitzeichen.

mbstate
Ein Zeiger auf ein mbstate_t -Objekt.

Rückgabewert

Gibt null oder bei einem Fehler einen errno-Wert zurück.

Hinweise

Die Funktion wcrtomb_s konvertiert ein Breitzeichen, beginnend beim angegebenen Konvertierungsstatus, der in mbstate enthalten ist, vom in wchar enthaltenen Wert in die von mbchar dargestellte Adresse. Der pReturnValue-Wert entspricht der Anzahl der konvertierten Bytes, jedoch nicht mehr als MB_CUR_MAX Bytes, oder -1 bei einem Fehler.

Wenn mbstate NULL ist, wird der interne Konvertierungsstatus mbstate_t verwendet. Wenn das in wchar enthaltene Zeichen kein entsprechendes Multibyte-Zeichen aufweist, ist der Wert von pReturnValue -1, und die Funktion gibt den errno Wert von EILSEQ.

Die wcrtomb_s Funktion unterscheidet sich von wctomb_sder _wctomb_s_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. Beispiel: Eine Anwendung würde wcsrlen anstelle von wcslen verwenden, wenn ein nachfolgender Aufruf von wcsrtombs_s anstelle von wcstombs_s verwendet würde.

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 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 wcrtomb_s-Funktion ist multithreadsicher, solange keine Funktion im aktuellen Thread setlocale aufruft, während diese Funktion ausgeführt wird und mbstate NULL ist.

Beispiel

// crt_wcrtomb_s.c
// This program converts a wide character
// to its corresponding multibyte character.
//

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    errno_t     returnValue;
    size_t      pReturnValue;
    mbstate_t   mbstate;
    size_t      sizeOfmbStr = 1;
    char        mbchar = 0;
    wchar_t*    wchar = L"Q\0";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    returnValue = wcrtomb_s(&pReturnValue, &mbchar, sizeof(char),
                            *wchar, &mbstate);
    if (returnValue == 0) {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wchar);
        printf(" was converted to a the \"%c\" ", mbchar);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

The corresponding wide character "Q" was converted to a the "Q" multibyte character.

Anforderungen

Siehe auch

Datenkonvertierung
Gebietsschema
Interpretation von Multibytezeichensequenzen
mbsinit