wcrtomb_s

Artykuł
02/27/2013

Przekonwertować szerokich znaków na jego reprezentacji znaków wielobajtowych.Wersja z wcrtomb z rozszerzeń zabezpieczeń opisane w Funkcje zabezpieczeń w CRT.

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

Parametry

[out]pReturnValue
Zwraca liczbę zapisanych bajtów lub -1, jeśli wystąpił błąd.
[out]mbchar
Wynikowy wielobajtowe konwersji znaków.
[w]sizeOfmbchar
Rozmiar mbchar zmiennej w bajtach.
[w]wchar
Szerokich znaków do konwertowania.
[w]mbstate
Wskaźnik do mbstate_t obiektu.

Wartość zwracana

Zwraca zero lub errno wartość, jeśli wystąpi błąd.

Uwagi

wcrtomb_s Funkcja konwertuje szerokich znaków, począwszy od stanu określonej konwersji zawartych w mbstate, od wartości zawartych w wchar, na adres, reprezentowana przez mbchar.pReturnValue Wartość będzie równa Liczba bajtów konwertowane, lecz nie więcej niż MB_CUR_MAX bajtów lub -1, jeśli wystąpił błąd.

Jeśli mbstate ma wartość null, wewnętrznego mbstate_t stan konwersji jest używany.Jeśli znak zawartych w wchar nie ma odpowiednich znaków wielobajtowych, wartość pReturnValue będzie -1 i funkcja zwróci errno wartość EILSEQ.

wcrtomb_s Funkcja różni się od wctomb_s, _wctomb_s_l przez jego restartability.Stan konwersji jest przechowywany w mbstate dla kolejnych zaproszeń na to samo lub inne funkcje Przerywalne.Wyniki są niezdefiniowane, przy użyciu funkcji Przerywalne i nonrestartable.Na przykład, aplikacja będzie korzystać z wcsrlen zamiast wcslen, jeśli kolejne wywołania wcsrtombs_s zostały użyte zamiastwcstombs_s.

W języku C++ za pomocą tej funkcji jest uproszczona poprzez overloads szablonu; overloads można automatycznie rozpoznać długość buforu (eliminując konieczność należy określić argument rozmiar) i automatycznie można zastąpić starszych, które nie są bezpieczne funkcje z ich odpowiednikami nowsze, bezpieczne.Aby uzyskać więcej informacji, zobacz Secure, szablon Overloads.

Wyjątki

wcrtomb_s Funkcja jest wielowątkowym bezpieczne tak długo, jak długo wywoła żadnej funkcji w bieżącym wątku setlocale podczas wykonywania tej funkcji oraz mbstate ma wartość null.

Przykład

// 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");
    }
}