wprintf(3) vswprintf

ОБЗОР

#include <stdio.h>
#include <wchar.h>


int wprintf(const wchar_t *format, ...);
int fwprintf(FILE *stream, const wchar_t *format, ...);
int swprintf(wchar_t *wcs, size_t maxlen,
const wchar_t *format, ...);

int vwprintf(const wchar_t *format, va_list args);
int vfwprintf(FILE *stream, const wchar_t *format, va_list args);
int vswprintf(wchar_t *wcs, size_t maxlen,
const wchar_t *format, va_list args);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

Все функции, показанные выше:

_XOPEN_SOURCE >= 500 || _ISOC99_SOURCE ||
_POSIX_C_SOURCE >= 200112L;
или cc -std=c99

ОПИСАНИЕ

Семейство функций wprintf() является эквивалентом семейства printf(3) для работы с широкими символами. Функции из этого семейства производят форматированный вывод широких символов.

Функции wprintf() и vwprintf() выводят широкие символы в поток stdout. stdout должен быть открыт не для байтовых операций; подробности смотрите в fwide(3).

Функции wprintf() и vwprintf() выводят широкие символы в поток stream. stream должен быть открыт не для байтовых операций; подробности смотрите в fwide(3).

Функции swprintf() и vswprintf() выводят широкие символы в массив широких символов. Программист должен быть уверен, что в wcs достаточно места для maxlen широких символов.

Все эти функции очень похожи на printf(3), vprintf(3), fprintf(3), vfprintf(3), sprintf(3), vsprintf(3), но отличаются от них в следующем:

  • Строка format представляет собой строку широких символов.
  • Вывод представляет собой широкие символы, а не байты.
  • Функции swprintf() и vswprintf() имеют аргумент maxlen, а sprintf(3) и vsprintf(3) нет (функции snprintf(3) и vsnprintf(3) имеют аргумент maxlen, но они не возвращают -1 при переполнении буфера в Linux).

Правила преобразования символов c и s различны:

c
Если модификатора l нет, то аргумент int преобразуется в широкий символ с помощью вызова функции btowc(3); затем полученный широкий символ записывается. Если модификатор l присутствует, то записывается аргумент (широкий символ) wint_t.
s
Если модификатор l отсутствует, то: аргумент const char * ожидается в виде указателя на массив элементов символьного типа (указателя на строку), содержащего многобайтовую символьную последовательность, находящуюся в исходном состоянии. Символы массива будут преобразованы в широкие символы последовательным вызовом функции mbrtowc(3) с учётом исходного состояния перед первым байтом. Получившиеся широкие символы будут записаны последовательно до завершающего (но не включая его) широкого символа null (L'\0'). Если указано количество символов, то записывается количество символов, меньшее определённого числа или равное ему. Обратите внимание, что количеством символов определяется число широких символов, а не байтов или позиций печати, которые будут записаны. Массив должен содержать завершающий байт null ('\0') на случай, если определённое в вызове количество байтов окажется недостаточным, то есть при конвертировании широкого символа возникнет ситуация, когда размер полученной последовательности слишком велик для размещения её в массиве. Если имеется модификатор l: аргумент const wchar_t * ожидается в виде указателя на массив широких символов. Широкие символы массива записываются до (но не включая) завершающего нулевого широкого символа. Если указано количество символов, то записывается количество символов, меньшее определённого числа или равное ему. Массив должен содержать завершающий нулевой байт на случай, если не указано количество или оно меньше или равно количеству широких символов в массиве.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Функции возвращают количество записанных широких символов, кроме завершающего нулевого символа для функций swprintf() и vswprintf(). В случае ошибки возвращается -1.

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).
ИнтерфейсАтрибутЗначение
wprintf(), fwprintf(),
swprintf(), vwprintf(),
vfwprintf(), vswprintf()
безвредность в нитяхбезвредно (MT-Safe locale)

СООТВЕТСТВИЕ СТАНДАРТАМ

POSIX.1-2001, POSIX.1-2008, C99.

ЗАМЕЧАНИЯ

Поведение wprintf() зависит от категории LC_CTYPE текущей локали.

Если строка format содержит широкие не ASCII символы, то программа будет работать корректно, только если категория LC_CTYPE текущей локали в момент выполнения действия совпадает с категорией LC_CTYPE текущей локали в момент компиляции. Это происходит потому, что представление wchar_t зависит от платформы и локали (glibc представляет широкие символы, используя универсальную кодовую таблицу Unicode (ISO-10646), но другие платформы могут не следовать этому. Кроме того, использование универсальных имён символов ISO C99 в форме \unnnn не решает этой проблемы). Следовательно, в многоязыковых программах строка format должна содержать только широкие символы из множества ASCII или должна создаваться во время выполнения с учётом многозыковости (например, с помощью gettext(3) или iconv(3), с последующим mbstowcs(3)).