wcrtomb_s

Artikel
06/09/2015

Konvertiert ein Breitzeichen in seine Mehrbytezeichendarstellung. Eine Version von wcrtomb mit werden, wie in Sicherheitsfunktionen in der CRT beschrieben.

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

[out] pReturnValue
Gibt die Anzahl an Bytes geschrieben oder -1 zurück, wenn ein Fehler aufgetreten ist.
[out] mbchar
Das resultierendes die Mehrbyte-Codepage konvertierte Zeichen.
[in] sizeOfmbchar
Die Größe der Variablen mbchar in Bytes.
[in] wchar
Bei einem Breitzeichen zu konvertieren.
[in] mbstate
Ein Zeiger auf ein mbstate_t-Objekt.

Rückgabewert

Gibt null oder ein errno-Wert, wenn ein Fehler auftritt.

Hinweise

Die wcrtomb_s-Funktion konvertiert ein Breitzeichen und beginnt im angegebenen Konvertierungszustand, der in mbstate, den Wert enthalten ist, der in wchar, in die Adresse enthalten wird, die durch mbchar dargestellt wird. Der Wert ist pReturnValue die Anzahl von Bytes konvertiert, jedoch höchstens MB_CUR_MAX Bytes oder -1, wenn ein Fehler aufgetreten ist.

Wenn mbstate NULL ist, wird der interne mbstate_t Konvertierungszustand verwendet. Wenn das Zeichen, das in wchar enthalten ist, kein entsprechendes Mehrbytezeichen ist, ist der Wert von pReturnValue -1 und die Funktion gibt errno den Wert EILSEQ zurück.

Die wcrtomb_s-Funktion unterscheidet sich von wctomb_s, _wctomb_s_l durch ihre Neustartfähigkeit. Der Konvertierungszustand wird in mbstate für nachfolgende Aufrufe an den gleichen oder anderen restartable Funktionen gespeichert. Ergebnisse werden undefiniert, wenn Sie die Verwendung von restartable und nonrestartable Funktionen kombiniert. Beispielsweise würde eine Anwendung wcsrlen statt wcslen verwenden, wenn ein nachfolgender Aufruf wcsrtombs_s statt wcstombs_s. verwendet wurden

In C++ unter Verwendung dieser Funktion wird durch Vorlagenüberladungen vereinfacht; die Überladungen können die Pufferlänge (die Anforderung automatisch beseitigend ableiten, einem Größenargument) anzugeben und sie können die älteren, nicht sicheren Funktionen durch die neueren, sicheren Entsprechungen automatisch ersetzen. Weitere Informationen finden Sie unter Sichere Vorlagenüberladungen.

Ausnahmen

Die Funktion wcrtomb_s ist multithreadsicher, solange keine Funktion im aktuellen Thread setlocale aufruft, wenn diese Funktion ausführt 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");
    }
}