wctomb_s, _wctomb_s_l

Статья
06/09/2015

Преобразует расширенный символ в соответствующий многобайтовый символ. Это версия wctomb, _wctomb_l с усовершенствованиями безопасности, как описано в Функции безопасности в 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	без изменений
any	>INT_MAX	EINVAL	без изменений
any	слишком мало	EINVAL	без изменений

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

Заметки

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

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

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

Требования

Подпрограмма	Обязательный заголовок
wctomb_s	<stdlib.h>
_wctomb_s_l	<stdlib.h>

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

Пример

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

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