wcstombs_s, _wcstombs_s_l

Статья
02/20/2013

Преобразование последовательноси расширенных символов в соответствующую последовательность многобайтовых символов.Это версия wcstombs, _wcstombs_l с усовершенствованиями безопасности, как описано в Средства безопасности в CRT.

errno_t wcstombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count 
);
errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t wcstombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count 
); // C++ only
template <size_t size>
errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

Параметры

[исходящий] pReturnValue
Количество символов для преобразования.
[исходящий] mbstr
Адрес буфера для результирующей преобразованной строки многобайтовых символов.
[in]sizeInBytes
Размер буфера mbstr (в байтах).
[входящий] wcstr
Указывает на преобразуемую строку расширенных символов.
[входящий] count
Максимальное количество расширенных символов, которое необходимо сохранить в буфере mbstr, не включая завершающий null символ или _TRUNCATE.
[входящий] locale
Используемый языковой стандарт.

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

Нуль, если успешно; код ошибки при неудаче.

Условие ошибки.	Возвращает значение и errno
mbstr содержит значение NULL и sizeInBytes > 0	EINVAL
Параметр wcstr содержит значение NULL	EINVAL
Буфер назначения слишком мал, чтобы вместить преобразованную строку (иначе count будет _TRUNCATE; см. примечания ниже)	ERANGE

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

Заметки

Функция wcstombs_s выполнит преобразование строки расширенных символов, содержащихся в wcstr, в многобайтовые, сохраняемые в буфере, на который указывает mbstr.Преобразование будет продолжаться для каждого символа до тех пор, пока одно не будет выполнено одно из следующих условий:

Не встретится расширенный символ null
Встретится расширенный символ, который нельзя преобразовать
Число байт, сохраненных в буфере mbstr не станет равным count.

Строка назначения всегда содержит завершающий null (даже в случае ошибки).

Если count является специальным значением _TRUNCATE, то преобразование wcstombs_s будет выполняться до тех пор, пока буфер назначения не будет заполнен с учетом завершающего признака null.

Если wcstombs_s успешно выполнит преобразование исходной строки, то значение, содержащее размер преобразованной строки в байтах с учетом завершающего символа конца строки null, будет помещено в *pReturnValue (предоставленное значение pReturnValue не равно NULL).Это происходит даже если аргумент mbstr равен NULL, таким образом, предоставляя возможность задать необходимый размер буфера.Обратите внимание, что если mbstr равен NULL, то count игнорируется.

Если wcstombs_s обнаруживает расширенный символ, который не может преобразовать в многобайтовый, то в *pReturnValue помещается значение 0, буфер назначения устанавливается равным пустой строке, errno устанавливается в EILSEQ, и возвращается EILSEQ.

Если последовательности, на которые указывают wcstr и mbstr, перекрываются, то поведение wcstombs_s не определено.

Примечание по безопасности
Убедитесь, что wcstr и mbstr не перекрываются, и что count правильно отражает количество расширенных символов для преобразования.

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

В C++ использование данных функций упрощено наличием шаблонных перегрузок; перегруженные методы могут автоматически определять длину буфера (что исключает необходимость указания аргумента с размером буфера), а также они могут автоматически заменять более старые, незащищенные функции их новыми безопасными аналогами.Дополнительные сведения см. в разделе Предоставляйте перегруженный шаблона.

Требования

Функция	Требуемый заголовок
wcstombs_s	<stdlib.h>

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

Пример

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

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t   i;
    char      *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t*pWCBuffer = L"Hello, world.";

    printf( "Convert wide-character string:\n" );

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE, 
               pWCBuffer, (size_t)BUFFER_SIZE );

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n",
     pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
    free(pMBBuffer);
    }
}