wctomb_s, _wctomb_s_l

  • Статья

Преобразует расширенный символ в соответствующий многобайтовый символ. Версия с _wctomb_lулучшениями безопасности, как описано в функциях wctombбезопасности в CRT.

Синтаксис

errno_t wctomb_s(
   int *pRetValue,
   char *mbchar,
   size_t sizeInBytes,
   wchar_t wchar
);
errno_t _wctomb_s_l(
   int *pRetValue,
   char *mbchar,
   size_t sizeInBytes,
   wchar_t wchar,
   _locale_t locale
);

Параметры

pRetValue
Число байтов или код, указывающий результат.

mbchar
Адрес последовательности многобайтовых символов.

sizeInBytes
Размер mbcharбуфера.

wchar
Преобразуемый широкий символ.

locale
Используемый языковой стандарт.

Возвращаемое значение

Возвращает нуль в случае успеха или код ошибки в случае неудачи.

Ситуации, которые могут привести к ошибке

mbchar sizeInBytes Возвращаемое значение pRetValue
NULL >0 EINVAL не изменено
любое >INT_MAX EINVAL не изменено
любое слишком мало EINVAL не изменено

Если возникает какая-либо из указанных выше ошибок, вызывается обработчик недопустимых параметров, как описано в разделе "Проверка параметров". Если выполнение может быть продолжено, функция wctomb возвращает значение EINVAL и устанавливает параметр errno в значение EINVAL.

Возвращаемое значение указывает, что значение EILSEQ , переданное через параметр wchar , не является допустимым широким символом.

Замечания

Функция wctomb_s преобразует свой аргумент wchar в соответствующий многобайтовый символ и сохраняет результат в mbchar. Эту функцию можно вызывать из любой точки в любой программе.

Если функция wctomb_s преобразует расширенный символ в многобайтовый символ, она помещает число байтов (которое никогда не превышает MB_CUR_MAX) в расширенном символе в целое число со знаком, на которое указывает pRetValue. Если wchar является расширенным нуль-символом (L '\0'), wctomb_s заполняет pRetValue символом 1. Если целевой указатель mbchar равен NULL, wctomb_s помещает значение 0 pRetValue. Если преобразование невозможно в текущем языковом стандарте, wctomb_s поместите -1 в pRetValue.

Функция wctomb_s использует текущий языковой стандарт для информации, обусловленной языковыми стандартами; функция _wctomb_s_l идентична за исключением того, что она использует переданный языковой стандарт. Дополнительные сведения см. в разделе Locale.

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.

Требования

Маршрут Обязательный заголовок
wctomb_s <stdlib.h>
_wctomb_s_l <stdlib.h>

Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример

Эта программа иллюстрирует поведение функции wctomb_s.

// crt_wctomb_s.cpp
#include <stdio.h>
#include <stdlib.h>

int main( void )
{
    int i;
    wchar_t wc = L'a';
    char *pmb = (char *)malloc( MB_CUR_MAX );

    printf_s( "Convert a wide character:\n" );
    wctomb_s( &i, pmb, MB_CUR_MAX, wc );
    printf_s( "   Characters converted: %u\n", i );
    printf_s( "   Multibyte character: %.1s\n\n", pmb );
}

Convert a wide character:
   Characters converted: 1
   Multibyte character: a

См. также

Преобразование данных
Локаль
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
WideCharToMultiByte