Namespaces
Variants

vwprintf, vfwprintf, vswprintf, vwprintf_s, vfwprintf_s, vswprintf_s, vsnwprintf_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Direct input/output
Formatted output
(C99) (C11) (C11) (C11) (C11)
vwprintf vfwprintf vswprintf vwprintf_s vfwprintf_s vswprintf_s vsnwprintf_s
(C95) (C95) (C95) (C11) (C11) (C11) (C11)
File positioning
Error handling
Operations on files
Определено в заголовке <wchar.h>
(1)
int vwprintf ( const wchar_t * format, va_list vlist ) ;
(начиная с C95)
(до C99)
int vwprintf ( const wchar_t * restrict format, va_list vlist ) ;
(начиная с C99)
(2)
int vfwprintf ( FILE * stream, const wchar_t * format, va_list vlist ) ;
(начиная с C95)
(до C99)
int vfwprintf ( FILE * restrict stream,
const wchar_t * restrict format, va_list vlist ) ;
(начиная с C99)
(3)
int vswprintf ( wchar_t * buffer, size_t bufsz,
const wchar_t * format, va_list vlist ) ;
(начиная с C95)
(до C99)
int vswprintf ( wchar_t * restrict buffer, size_t bufsz,
const wchar_t * restrict format, va_list vlist ) ;
(начиная с C99)
int vwprintf_s ( const wchar_t * restrict format, va_list vlist ) ;
(4) (начиная с C11)
int vfwprintf_s ( FILE * restrict stream,
const wchar_t * restrict format, va_list vlist ) ;
(5) (начиная с C11)
int vswprintf_s ( wchar_t * restrict buffer, rsize_t bufsz,
const wchar_t * restrict format, va_list vlist ) ;
(6) (начиная с C11)
int vsnwprintf_s ( wchar_t * restrict buffer, rsize_t bufsz,
const wchar_t * restrict format, va_list vlist ) ;
(7) (начиная с C11)

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

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

Содержание

Параметры

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


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

  • вводный % символ.
  • (необязательно) один или несколько флагов, изменяющих поведение преобразования:
  • - : результат преобразования выравнивается по левому краю поля (по умолчанию выравнивается по правому краю).
  • + : знак знаковых преобразований всегда добавляется перед результатом преобразования (по умолчанию результат предваряется минусом только когда он отрицательный).
  • пробел : если результат знакового преобразования не начинается со знака или является пустым, перед результатом добавляется пробел. Игнорируется если присутствует флаг + .
  • # : альтернативная форма преобразования. Смотрите таблицу ниже для точных эффектов, иначе поведение не определено.
  • 0 : для целочисленных и преобразований чисел с плавающей точкой, ведущие нули используются для заполнения поля вместо пробелов . Для целых чисел игнорируется если точность указана явно. Для других преобразований использование этого флага приводит к неопределенному поведению. Игнорируется если присутствует флаг - .
  • (необязательно) целочисленное значение или * , определяющее минимальную ширину поля. Результат дополняется символами пробела (по умолчанию) при необходимости слева при выравнивании по правому краю или справа при выравнивании по левому краю. В случае использования * , ширина задается дополнительным аргументом типа 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 с обнуленным состоянием преобразования.
  • Precision определяет максимальное количество широких символов для записи. Если Precision не указана, записываются все широкие символы до первого нулевого терминатора (исключая его).
  • Если используется спецификатор 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,4) Количество записанных широких символов в случае успеха или отрицательное значение при возникновении ошибки.
3) Количество записанных широких символов в случае успеха или отрицательное значение при возникновении ошибки. Если результирующая строка была усечена из-за ограничения bufsz , функция возвращает общее количество символов (не включая завершающий нулевой широкий символ), которое было бы записано, если бы ограничение не было наложено.
2,5) количество широких символов, переданных в выходной поток, или отрицательное значение, если произошла ошибка вывода, ошибка нарушения ограничений времени выполнения или ошибка кодирования.
6) количество широких символов, записанных в buffer , не включая нулевой широкий символ (который всегда записывается, пока buffer не является нулевым указателем и bufsz не равен нулю и не больше RSIZE_MAX/sizeof(wchar_t) ), или ноль при нарушениях ограничений времени выполнения, и отрицательное значение при ошибках кодирования.
7) количество широких символов, не включая завершающий нулевой символ (который всегда записывается, пока buffer не является нулевым указателем и bufsz не равен нулю и не больше RSIZE_MAX/sizeof(wchar_t) ), которые были бы записаны в buffer если бы bufsz игнорировался, или отрицательное значение при нарушении ограничений времени выполнения или ошибке кодирования.

Примечания

Все эти функции вызывают va_arg как минимум один раз, значение arg становится неопределённым после возврата. Эти функции не вызывают va_end , и это должно быть выполнено вызывающей стороной.

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

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

Пример

Запустить этот код 
#include <locale.h>
#include <stdarg.h>
#include <stddef.h>
#include <stdio.h>
#include <time.h>
#include <wchar.h>
void debug_wlog(const wchar_t* fmt, ...)
{
    struct timespec ts;
    timespec_get(&ts, TIME_UTC);
    char time_buf[100];
    size_t rc = strftime(time_buf, sizeof time_buf, "%D %T", gmtime(&ts.tv_sec));
    snprintf(time_buf + rc, sizeof time_buf - rc, ".%06ld UTC", ts.tv_nsec / 1000);
    va_list args;
    va_start(args, fmt);
    wchar_t buf[1024];
    int rc2 = vswprintf(buf, sizeof buf / sizeof *buf, fmt, args);
    va_end(args);
    if(rc2 > 0)
       wprintf(L"%s [debug]: %ls\n", time_buf, buf);
    else
       wprintf(L"%s [debug]: (string too long)\n", time_buf);
}
int main(void)
{
    setlocale(LC_ALL, "");
    debug_wlog(L"Logging, %d, %d, %d", 1, 2, 3);
}

Возможный вывод: 

02/20/15 22:12:38.476575 UTC [debug]: Logging, 1, 2, 3

Ссылки

  • Стандарт C23 (ISO/IEC 9899:2024):
  • 7.29.2.5 Функция vfwprintf (стр.: TBD)
  • 7.29.2.7 Функция vswprintf (стр.: TBD)
  • 7.29.2.9 Функция vwprintf (стр.: TBD)
  • K.3.9.1.6 Функция vfwprintf_s (стр.: TBD)
  • K.3.9.1.8 Функция vsnwprintf_s (стр.: TBD)
  • K.3.9.1.9 Функция vswprintf_s (стр.: TBD)
  • K.3.9.1.11 Функция vwprintf_s (стр.: TBD)
  • Стандарт C17 (ISO/IEC 9899:2018):
  • 7.29.2.5 Функция vfwprintf (стр.: TBD)
  • 7.29.2.7 Функция vswprintf (стр.: TBD)
  • 7.29.2.9 Функция vwprintf (стр.: TBD)
  • K.3.9.1.6 Функция vfwprintf_s (стр.: TBD)
  • K.3.9.1.8 Функция vsnwprintf_s (стр.: TBD)
  • K.3.9.1.9 Функция vswprintf_s (стр.: TBD)
  • K.3.9.1.11 Функция vwprintf_s (стр.: TBD)
  • Стандарт C11 (ISO/IEC 9899:2011):
  • 7.29.2.5 Функция vfwprintf (стр: 417-418)
  • 7.29.2.7 Функция vswprintf (стр: 419)
  • 7.29.2.9 Функция vwprintf (стр: 420)
  • K.3.9.1.6 Функция vfwprintf_s (стр: 632)
  • K.3.9.1.8 Функция vsnwprintf_s (стр: 633-634)
  • K.3.9.1.9 Функция vswprintf_s (стр: 634-635)
  • K.3.9.1.11 Функция vwprintf_s (стр: 636)
  • Стандарт C99 (ISO/IEC 9899:1999):
  • 7.24.2.5 Функция vfwprintf (стр: 363)
  • 7.24.2.7 Функция vswprintf (стр: 364)
  • 7.24.2.9 Функция vwprintf (стр: 365)

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

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