wcrtomb_s

Przekonwertuj znak szeroki na reprezentację znaków wielobajtowych. Wersja z ulepszeniami zabezpieczeń wcrtomb zgodnie z opisem w temacie Funkcje zabezpieczeń w narzędziu CRT.

Składnia

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

pReturnValue
Zwraca liczbę bajtów zapisanych lub -1, jeśli wystąpił błąd.

mbchar
Wynikowy znak wielobajtowy przekonwertowany.

sizeOfmbchar
Rozmiar zmiennej mbchar w bajtach.

wchar
Szeroki znak do konwersji.

mbstate
Wskaźnik do mbstate_t obiektu.

Wartość zwracana

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

Uwagi

Funkcja wcrtomb_s konwertuje szeroki znak, zaczynając od określonego stanu konwersji zawartego w , z wartości zawartej w wcharmbstate, na adres reprezentowany przez mbchar. Wartość pReturnValue będzie liczbą przekonwertowanych bajtów, ale nie więcej niż MB_CUR_MAX bajty lub -1, jeśli wystąpił błąd.

Jeśli mbstate ma wartość null, używany jest stan konwersji wewnętrznej mbstate_t . Jeśli znak zawarty w obiekcie wchar nie ma odpowiedniego znaku wielobajtowego, wartość pReturnValue to -1, a funkcja zwraca errno wartość EILSEQ.

Funkcja wcrtomb_s różni się od wctomb_sfunkcji , _wctomb_s_l dzięki możliwości ponownego uruchamiania. Stan konwersji jest przechowywany dla mbstate kolejnych wywołań do tych samych lub innych funkcji możliwych do ponownego uruchomienia. Wyniki są niezdefiniowane podczas mieszania funkcji możliwych do ponownego uruchomienia i niezwiązanych z uruchamianiem. Na przykład aplikacja będzie używać wcsrlen zamiast wcslen, jeśli kolejne wywołanie wcsrtombs_s zostało użyte zamiast wcstombs_s.

W języku C++używanie tej funkcji jest uproszczone przez przeciążenia szablonu; przeciążenia mogą automatycznie wnioskować długość buforu (eliminując konieczność określenia argumentu rozmiaru) i mogą automatycznie zastępować starsze, niezabezpieczone funkcje nowszymi, bezpiecznymi odpowiednikami. Aby uzyskać więcej informacji, zobacz Bezpieczne przeciążenia szablonów.

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Wyjątki

wcrtomb_s Funkcja jest bezpieczna wielowątkowość, o ile nie ma funkcji w bieżących wywołaniach setlocale wątku, gdy ta funkcja jest wykonywana, a mbstate parametr 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");
    }
}

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

Wymagania

Procedura	Wymagany nagłówek
wcrtomb_s	<wchar.h>

Zobacz też

Konwersja danych
ustawienia regionalne
Interpretacja sekwencji znaków wielobajtowych
mbsinit