Namespaces
Variants

wprintf, fwprintf, swprintf, wprintf_s, fwprintf_s, swprintf_s, snwprintf_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Direct input/output
Formatted output
(C99) (C11) (C11) (C11) (C11)
wprintf fwprintf swprintf wprintf_s fwprintf_s swprintf_s snwprintf_s
(C95) (C95) (C95) (C11) (C11) (C11) (C11)
File positioning
Error handling
Operations on files
Определено в заголовке <wchar.h>
(1)
int wprintf ( const wchar_t * format, ... ) ;
(начиная с C95)
(до C99)
int wprintf ( const wchar_t * restrict format, ... ) ;
(начиная с C99)
(2)
int fwprintf ( FILE * stream, const wchar_t * format, ... ) ;
(начиная с C95)
(до C99)
int fwprintf ( FILE * restrict stream,
const wchar_t * restrict format, ... ) ;
(начиная с C99)
(3)
int swprintf ( wchar_t * buffer, size_t bufsz,
const wchar_t * format, ... ) ;
(начиная с C95)
(до C99)
int swprintf ( wchar_t * restrict buffer, size_t bufsz,
const wchar_t * restrict format, ... ) ;
(начиная с C99)
int wprintf_s ( const wchar_t * restrict format, ... ) ;
(4) (начиная с C11)
int fwprintf_s ( FILE * restrict stream,
const wchar_t * restrict format, ... ) ;
(5) (начиная с C11)
int swprintf_s ( wchar_t * restrict buffer, rsize_t bufsz,
const wchar_t * restrict format, ... ) ;
(6) (начиная с C11)
int snwprintf_s ( wchar_t * restrict s, rsize_t n,
const wchar_t * restrict format, ... ) ;
(7) (начиная с C11)

Загружает данные из указанных местоположений, преобразует их в эквиваленты широких строк и записывает результаты в различные приемники.

1) Записывает результаты в stdout .
2) Записывает результаты в файловый поток stream .
3) Если bufsz больше нуля, записывает результаты в широкую строку buffer . Записывается не более bufsz - 1 широких символов, за которыми следует нулевой широкий символ. Если bufsz равен нулю, ничего не записывается (и buffer может быть нулевым указателем).
4-6) То же, что и (1-3) , за исключением того, что следующие ошибки обнаруживаются во время выполнения и вызывают текущую установленную функцию обработки ограничений :
  • спецификатор преобразования %n присутствует в format
  • любой из аргументов, соответствующих %s , является нулевым указателем
  • format или buffer является нулевым указателем
  • bufsz равен нулю или больше RSIZE_MAX / sizeof ( wchar_t )
  • возникают ошибки кодирования в любом из спецификаторов преобразования строк и символов
  • (только для swprintf_s ) количество широких символов для записи, включая нулевой, превысило бы bufsz .
7) То же, что и (6) , за исключением того, что результат будет усечён для размещения в массиве, на который указывает s.
Как и все функции с проверкой границ, wprintf_s , fwprintf_s , swprintf_s , и snwprintf_s гарантированно доступны только если __STDC_LIB_EXT1__ определён реализацией и если пользователь определит __STDC_WANT_LIB_EXT1__ как целочисленную константу 1 перед включением <stdio.h> .

Содержание

Параметры

stream - выходной файловый поток для записи
buffer - указатель на строку широких символов для записи
bufsz - может быть записано до bufsz - 1 широких символов плюс нулевой терминатор
format - указатель на нуль-терминированную широкую строку, определяющую способ интерпретации данных
... - аргументы, определяющие данные для вывода. Если любой аргумент после стандартных преобразований аргументов не соответствует типу, ожидаемому соответствующим спецификатором преобразования, или если аргументов меньше, чем требуется по format , поведение не определено. Если аргументов больше, чем требуется по format , лишние аргументы вычисляются и игнорируются.


Строка формата состоит из обычных широких символов (за исключением % ), которые копируются без изменений в выходной поток, и спецификаций преобразования. Каждая спецификация преобразования имеет следующий формат:

  • вводный % символ.
  • (необязательно) один или несколько флагов, изменяющих поведение преобразования:
  • - : результат преобразования выравнивается по левому краю в пределах поля (по умолчанию выравнивается по правому краю).
  • + : знак знаковых преобразований всегда добавляется перед результатом преобразования (по умолчанию результат предваряется минусом только когда он отрицательный).
  • space : если результат знакового преобразования не начинается с символа знака или является пустым, перед результатом добавляется пробел. Игнорируется если присутствует флаг + .
  • # : альтернативная форма преобразования выполняется. Смотрите таблицу ниже для точных эффектов, иначе поведение не определено.
  • 0 : для целочисленных и преобразований чисел с плавающей точкой, ведущие нули используются для заполнения поля вместо символов space . Для целых чисел игнорируется если точность явно указана. Для других преобразований использование этого флага приводит к неопределенному поведению. Игнорируется если присутствует флаг - .
  • (необязательно) целочисленное значение или * , определяющее минимальную ширину поля. Результат дополняется символами пробела (по умолчанию) при необходимости слева при выравнивании по правому краю или справа при выравнивании по левому краю. В случае использования * , ширина задается дополнительным аргументом типа int , который указывается перед аргументом для преобразования и аргументом, задающим точность, если он предоставлен. Если значение аргумента отрицательное, это приводит к указанию флага - и положительной ширины поля (Примечание: Это минимальная ширина: значение никогда не усекается.).
  • (необязательно) . за которым следует целое число или * , либо ничего, что определяет точность преобразования. В случае использования * , точность задается дополнительным аргументом типа int , который указывается перед преобразуемым аргументом, но после аргумента, задающего минимальную ширину поля, если таковой указан. Если значение этого аргумента отрицательное, оно игнорируется. Если не указано ни число, ни * , точность принимается равной нулю. Смотрите таблицу ниже для точных эффектов точности .
  • (необязательный) модификатор длины который указывает размер аргумента (в сочетании со спецификатором формата преобразования он определяет тип соответствующего аргумента).
  • спецификатор формата преобразования.

Доступны следующие спецификаторы формата:

Спецификатор
преобразования 		Объяснение Ожидаемый
тип аргумента
Модификатор длины→ hh h нет l ll j z t L
Доступно только с C99→ Да Да Да Да Да
% Выводит символ % . Полная спецификация преобразования должна быть %% . N/A N/A N/A N/A N/A N/A N/A N/A N/A
c

Записывает один символ .

  • Аргумент сначала преобразуется в wchar_t как если бы вызывалась функция btowc .
  • Если используется модификатор l , аргумент wint_t сначала преобразуется в wchar_t .
N/A N/A
int
wint_t
N/A N/A N/A N/A N/A
s

Записывает строку символов .

  • Аргумент должен быть указателем на начальный элемент массива символов, содержащего многобайтовую последовательность символов, начинающуюся в начальном состоянии сдвига, которая преобразуется в массив широких символов как при вызове mbrtowc с обнуленным состоянием преобразования.
  • Точность определяет максимальное количество широких символов для записи. Если Точность не указана, записываются все широкие символы до первого нулевого терминатора (исключая его).
  • Если используется спецификатор l , аргумент должен быть указателем на начальный элемент массива wchar_t .
N/A N/A
char *
wchar_t *
N/A N/A N/A N/A N/A
d
i

Преобразует знаковое целое число в десятичное представление [-]dddd .

  • Точность определяет минимальное количество отображаемых цифр. Точность по умолчанию равна 1 .
  • Если и преобразованное значение, и точность равны ​ 0 ​ , преобразование не выдает символов.
  • Для модификатора z ожидаемый тип аргумента - знаковая версия size_t .
signed char
short
int
long
long long
※
N/A
o

Преобразует беззнаковое целое число в восьмеричное представление oooo .

  • Точность определяет минимальное количество отображаемых цифр. Точность по умолчанию равна 1 .
  • Если и преобразованное значение, и точность равны ​ 0 ​ , преобразование не выводит символов.
  • В альтернативной реализации точность увеличивается при необходимости для записи одного ведущего нуля. В этом случае, если и преобразованное значение, и точность равны ​ 0 ​ , записывается один ​ 0 ​ .
unsigned char
unsigned short
unsigned int
unsigned long
unsigned long long
беззнаковая версия ptrdiff_t
N/A
x
X

Преобразует беззнаковое целое число в шестнадцатеричное представление hhhh .

  • Для преобразования x используются буквы abcdef .
  • Для преобразования X используются буквы ABCDEF .
  • Точность определяет минимальное количество отображаемых цифр. Точность по умолчанию равна 1 .
  • Если и преобразованное значение, и точность равны ​ 0 ​ , преобразование не выводит символов.
  • В альтернативной реализации к результатам добавляется префикс 0x или 0X , если преобразованное значение ненулевое.
N/A
u

Преобразует беззнаковое целое число в десятичное представление dddd .

  • Точность определяет минимальное количество отображаемых цифр.
  • Точность по умолчанию равна 1 .
  • Если и преобразованное значение, и точность равны ​ 0 ​ , преобразование не выводит символов.
N/A
f
F (C99)

Преобразует число с плавающей точкой в десятичную запись в формате [-]ddd.ddd .

  • Точность определяет точное количество цифр после десятичного разделителя.
  • Точность по умолчанию составляет 6 .
  • В альтернативной реализации десятичный разделитель записывается даже если за ним не следуют цифры.
  • Для стиля преобразования бесконечности и не-числа смотрите примечания .
N/A N/A
double
double (C99)
N/A N/A N/A N/A
long double
e
E

Преобразует число с плавающей запятой в экспоненциальную десятичную запись.

  • Для стиля преобразования e используется формат [-]d.ddd  e ±dd .
  • Для стиля преобразования E используется формат [-]d.ddd  E ±dd .
  • Экспонента содержит как минимум две цифры, дополнительные цифры используются только при необходимости.
  • Если значение равно ​ 0 ​ , экспонента также равна ​ 0 ​ .
  • Точность определяет точное количество цифр после десятичного разделителя.
  • Точность по умолчанию составляет 6 .
  • В альтернативной реализации десятичный разделитель записывается даже если после него не следует цифр.
  • Для преобразования бесконечности и не-числа смотрите примечания .
N/A N/A N/A N/A N/A N/A
a
A

(C99)

Преобразует число с плавающей точкой в шестнадцатеричную экспоненциальную нотацию.

  • Для стиля преобразования a используется формат [-]  0x h.hhh  p ±d .
  • Для стиля преобразования A используется формат [-]  0X h.hhh  P ±d .
  • Первая шестнадцатеричная цифра не равна 0 , если аргумент является нормализованным значением с плавающей точкой.
  • Если значение равно ​ 0 ​ , экспонента также равна ​ 0 ​ .
  • Точность определяет точное количество цифр, которые должны отображаться после символа шестнадцатеричной точки.
  • Точность по умолчанию достаточна для точного представления значения.
  • В альтернативной реализации символ десятичной точки записывается даже если после него не следует цифр.
  • Для преобразования бесконечности и не-числа смотрите примечания .
N/A N/A N/A N/A N/A N/A
g
G

Преобразует число с плавающей точкой в десятичную или экспоненциальную десятичную запись в зависимости от значения и точности .

  • Для стиля преобразования g будет выполнено преобразование со стилем e или f .
  • Для стиля преобразования G будет выполнено преобразование со стилем E или f (до C99) F (начиная с C99) .
  • Пусть P равно точности, если она ненулевая, 6 если точность не указана, или 1 если точность равна ​ 0 ​ . Тогда, если преобразование со стилем E имело бы показатель степени X :
    • Если P > X ≥ −4 , преобразование выполняется со стилем f или F (начиная с C99) и точностью P − 1 − X .
    • В противном случае преобразование выполняется со стилем e или E и точностью P − 1 .
  • Если не запрошено альтернативное представление , завершающие нули удаляются, а также удаляется десятичная точка, если не осталось дробной части.
  • Для преобразования бесконечности и не-числа смотрите примечания .
Н/Д Н/Д Н/Д Н/Д Н/Д Н/Д
n

Возвращает количество записанных символов на данный момент этим вызовом функции.

  • Результат записывается в значение, на которое указывает аргумент.
  • Спецификатор не может содержать никаких флагов , ширины поля или точности .
  • Для модификатора z ожидаемый тип аргумента - S * , где S - это знаковая версия size_t .
signed char *
short *
int *
long *
long long *
※
N/A
p

Выводит определяемую реализацией последовательность символов, определяющую указатель .

N/A N/A
void *
N/A N/A N/A N/A N/A N/A
Примечания

Функции преобразования чисел с плавающей точкой преобразуют бесконечность в inf или infinity . Какой именно вариант используется, определяется реализацией.

Не-число преобразуется в nan или nan( char_sequence ) . Какой именно вариант используется, определяется реализацией.

Преобразования F , E , G , A выводят INF , INFINITY , NAN вместо этого.

Спецификатор преобразования, используемый для вывода char , unsigned char , signed char , short и unsigned short , ожидает продвинутые типы стандартных продвижений аргументов , но перед выводом его значение будет преобразовано в char , unsigned char , signed char , short и unsigned short . Безопасно передавать значения этих типов из-за продвижения, которое происходит при вызове вариативной функции.

Правильные спецификаторы преобразования для типов символов фиксированной ширины ( int8_t и т.д.) определены в заголовочном файле <inttypes.h> (хотя PRIdMAX , PRIuMAX и т.д. являются синонимами для %jd , %ju и т.д.).

Спецификатор преобразования с записью в память %n является частой целью атак безопасности, когда строки формата зависят от пользовательского ввода и не поддерживается семейством функций с проверкой границ printf_s (начиная с C11) .

Существует точка следования после действия каждого спецификатора преобразования; это позволяет сохранять несколько результатов %n в одной переменной или, как крайний случай, выводить строку, измененную предыдущим %n в том же вызове.

Если спецификация преобразования неверна, поведение не определено.

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

1,2) Количество записанных широких символов в случае успеха или отрицательное значение в случае ошибки.
3) Количество записанных широких символов (без учёта завершающего нулевого широкого символа) в случае успеха, или отрицательное значение в случае ошибки кодирования, либо если количество генерируемых символов было равно или превышало bufsz (включая случай, когда bufsz равен нулю).
4,5) Количество записанных широких символов в случае успеха или отрицательное значение в случае ошибки.
6) Количество широких символов (не включая завершающий нуль), которые были записаны в buffer . Возвращает отрицательное значение при ошибках кодирования и переполнении. Возвращает ноль при всех остальных ошибках.
7) Количество широких символов (не включая завершающий нуль), которые были бы записаны в buffer если бы bufsz был достаточно большим, или отрицательное значение при возникновении ошибки. (то есть запись была успешной и завершённой только если возвращаемое значение неотрицательно и меньше bufsz )

Примечания

В то время как узкие строки предоставляют snprintf , что позволяет определить необходимый размер выходного буфера, для широких строк нет эквивалента (до snwprintf_s ) (начиная с C11) , и для определения размера буфера программе может потребоваться вызвать swprintf , проверить возвращаемое значение и перераспределить буфер большего размера, повторяя попытку до успешного выполнения.

snwprintf_s , в отличие от swprintf_s , будет обрезать результат, чтобы он поместился в массив, на который указывает buffer , несмотря на то, что усечение рассматривается как ошибка большинством функций с проверкой границ.

Пример

Запустить этот код 
#include <locale.h>
#include <wchar.h>
int main(void)
{
    char narrow_str[] = "z\u00df\u6c34\U0001f34c";
                  // или "zß水🍌"
                  // или "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9f\x8d\x8c";
    wchar_t warr[29]; // ожидаемая строка состоит из 28 символов плюс нуль-терминатор
    setlocale(LC_ALL, "en_US.utf8");
    swprintf(warr, sizeof warr / sizeof* warr,
             L"Converted from UTF-8: '%s'", narrow_str);
    wprintf(L"%ls\n", warr);
}

Вывод: 

Converted from UTF-8: 'zß水🍌'

Ссылки

  • Стандарт C23 (ISO/IEC 9899:2024):
  • 7.29.2.1 Функция fwprintf (стр.: TBD)
  • 7.29.2.3 Функция swprintf (стр.: TBD)
  • 7.29.2.11 Функция wprintf (стр.: TBD)
  • K.3.9.1.1 Функция fwprintf_s (стр.: TBD)
  • K.3.9.1.4 Функция swprintf_s (стр.: TBD)
  • K.3.9.1.13 Функция wprintf_s (стр.: TBD)
  • Стандарт C17 (ISO/IEC 9899:2018):
  • 7.29.2.1 Функция fwprintf (стр.: TBD)
  • 7.29.2.3 Функция swprintf (стр.: TBD)
  • 7.29.2.11 Функция wprintf (стр.: TBD)
  • K.3.9.1.1 Функция fwprintf_s (стр.: TBD)
  • K.3.9.1.4 Функция swprintf_s (стр.: TBD)
  • K.3.9.1.13 Функция wprintf_s (стр.: TBD)
  • Стандарт C11 (ISO/IEC 9899:2011):
  • 7.29.2.1 Функция fwprintf (стр. 403-410)
  • 7.29.2.3 Функция swprintf (стр. 416)
  • 7.29.2.11 Функция wprintf (стр. 421)
  • K.3.9.1.1 Функция fwprintf_s (стр. 628)
  • K.3.9.1.4 Функция swprintf_s (стр. 630-631)
  • K.3.9.1.13 Функция wprintf_s (стр. 637-638)
  • Стандарт C99 (ISO/IEC 9899:1999):
  • 7.24.2.1 Функция fwprintf (стр: 349-356)
  • 7.24.2.3 Функция swprintf (стр: 362)
  • 7.24.2.11 Функция wprintf (стр: 366)

Смотрите также

(C99) (C11) (C11) (C11) (C11)
выводит форматированные данные в stdout , файловый поток или буфер
(функция)
(C95) (C95) (C95) (C11) (C11) (C11) (C11)
выводит форматированные данные широких символов в stdout , файловый поток
или буфер, используя список переменных аргументов
(функция)
(C95)
записывает широкую строку в файловый поток
(функция)
Документация C++ для wprintf , fwprintf , swprintf