Namespaces
Variants

vprintf, vfprintf, vsprintf, vsnprintf, vprintf_s, vfprintf_s, vsprintf_s, vsnprintf_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Direct input/output
Formatted output
vprintf vfprintf vsprintf vsnprintf vprintf_s vfprintf_s vsprintf_s vsnprintf_s
(C99) (C11) (C11) (C11) (C11)
(C95) (C95) (C95) (C11) (C11) (C11) (C11)
File positioning
Error handling
Operations on files
Определено в заголовке <stdio.h>
(1)
int vprintf ( const char * format, va_list vlist ) ;
(до C99)
int vprintf ( const char * restrict format, va_list vlist ) ;
(начиная с C99)
(2)
int vfprintf ( FILE * stream, const char * format, va_list vlist ) ;
(до C99)
int vfprintf ( FILE * restrict stream, const char * restrict format,
va_list vlist ) ;
(начиная с C99)
(3)
int vsprintf ( char * buffer, const char * format, va_list vlist ) ;
(до C99)
int vsprintf ( char * restrict buffer, const char * restrict format,
va_list vlist ) ;
(начиная с C99)
int vsnprintf ( char * restrict buffer, size_t bufsz,
const char * restrict format, va_list vlist ) ;
(4) (начиная с C99)
int vprintf_s ( const char * restrict format, va_list vlist ) ;
(5) (начиная с C11)
int vfprintf_s ( FILE * restrict stream, const char * restrict format,
va_list vlist ) ;
(6) (начиная с C11)
int vsprintf_s ( char * restrict buffer, rsize_t bufsz,
const char * restrict format, va_list vlist ) ;
(7) (начиная с C11)
int vsnprintf_s ( char * restrict buffer, rsize_t bufsz,
const char * restrict format, va_list vlist ) ;
(8) (начиная с C11)

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

1) Записывает результаты в stdout .
2) Записывает результаты в файловый поток stream .
3) Записывает результаты в строку символов buffer .
4) Записывает результаты в строку символов buffer . Записывается не более bufsz - 1 символов. Результирующая строка символов будет завершена нулевым символом, если только bufsz не равен нулю. Если bufsz равен нулю, ничего не записывается и buffer может быть нулевым указателем, однако возвращаемое значение (количество байтов, которое было бы записано без учёта нулевого терминатора) всё равно вычисляется и возвращается.
5-8) То же, что и (1-4) , за исключением того, что следующие ошибки обнаруживаются во время выполнения и вызывают текущую установленную constraint handler функцию:
  • спецификатор преобразования %n присутствует в format
  • любой из аргументов, соответствующих %s , является нулевым указателем
  • format или buffer является нулевым указателем
  • bufsz равен нулю или больше RSIZE_MAX
  • возникают ошибки кодирования в любом из спецификаторов преобразования строк и символов
  • (только для vsprintf_s ), строка для сохранения в buffer (включая завершающий нуль) превысила бы bufsz
Как и все функции с проверкой границ, vprintf_s , vfprintf_s , vsprintf_s и vsnprintf_s гарантированно доступны только если __STDC_LIB_EXT1__ определено реализацией и если пользователь определяет __STDC_WANT_LIB_EXT1__ как целочисленную константу 1 перед включением <stdio.h> .

Содержание

Параметры

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

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

  • вводный % символ.
  • (необязательно) один или несколько флагов, изменяющих поведение преобразования:
  • - : результат преобразования выравнивается по левому краю в пределах поля (по умолчанию выравнивается по правому краю).
  • + : знак знаковых преобразований всегда добавляется перед результатом преобразования (по умолчанию минус добавляется только для отрицательных значений).
  • 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

Выводит один символ .

  • Аргумент сначала преобразуется в unsigned char .
  • Если используется модификатор l , аргумент сначала преобразуется в строку символов как при использовании %ls с аргументом wchar_t [ 2 ] .
N/A N/A
int
wint_t
N/A N/A N/A N/A N/A
s

Выводит строку символов .

  • Аргумент должен быть указателем на начальный элемент массива символов.
  • Точность определяет максимальное количество байт для записи. Если Точность не указана, записываются все байты до первого нулевого терминатора (исключая его).
  • Если используется спецификатор l , аргумент должен быть указателем на начальный элемент массива wchar_t , который преобразуется в массив char как при вызове функции wcrtomb с нулевым состоянием преобразования.
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/A N/A N/A N/A N/A N/A
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 или 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-3) Количество записанных символов при успешном выполнении или отрицательное значение при возникновении ошибки.
4) Количество записанных символов в случае успеха или отрицательное значение при ошибке. Если результирующая строка обрезана из-за ограничения buf_size , функция возвращает общее количество символов (не включая завершающий нулевой байт), которое было бы записано, если бы ограничение не было наложено.
5,6) количество символов, переданных в выходной поток, или отрицательное значение, если произошла ошибка вывода, ошибка нарушения ограничений времени выполнения или ошибка кодировки.
7) количество символов, записанных в buffer , не включая нулевой символ (который всегда записывается, пока buffer не является нулевым указателем и bufsz не равен нулю и не больше RSIZE_MAX ), или ноль при нарушениях ограничений времени выполнения, и отрицательное значение при ошибках кодирования
8) количество символов, не включая завершающий нулевой символ (который всегда записывается, пока buffer не является нулевым указателем и bufsz не равен нулю и не больше RSIZE_MAX ), которые были бы записаны в buffer если бы bufsz игнорировался, или отрицательное значение при нарушении ограничений времени выполнения или ошибке кодирования

Примечания

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

vsnprintf_s , в отличие от vsprintf_s , будет обрезать результат, чтобы он поместился в массив, на который указывает buffer .

Реализация функции vsnprintf_s в Microsoft CRT не соответствует стандарту C. Версия Microsoft имеет дополнительный параметр size_t count на третьей позиции, который содержит максимальное количество символов для записи, не включая нулевой терминатор. Этот параметр может отличаться от размера буфера, предоставленного через параметр size_t bufsz .

Пример

Запустить этот код 
#include <stdarg.h>
#include <stdio.h>
#include <time.h>
void debug_log(const char* 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 args1;
    va_start(args1, fmt);
    va_list args2;
    va_copy(args2, args1);
    char buf[1+vsnprintf(NULL, 0, fmt, args1)];
    va_end(args1);
    vsnprintf(buf, sizeof buf, fmt, args2);
    va_end(args2);
    printf("%s [debug]: %s\n", time_buf, buf);
}
int main(void)
{
    debug_log("Logging, %d, %d, %d", 1, 2, 3);
}

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

02/20/15 21:58:09.072683 UTC [debug]: Logging, 1, 2, 3

Ссылки

  • Стандарт C23 (ISO/IEC 9899:2024):
  • 7.21.6.8 Функция vfprintf (стр.: TBD)
  • 7.21.6.10 Функция vprintf (стр.: TBD)
  • 7.21.6.12 Функция vsnprintf (стр.: TBD)
  • 7.21.6.13 Функция vsprintf (стр.: TBD)
  • K.3.5.3.8 Функция vfprintf_s (стр.: TBD)
  • K.3.5.3.10 Функция vprintf_s (стр.: TBD)
  • K.3.5.3.12 Функция vsnprintf_s (стр.: TBD)
  • K.3.5.3.13 Функция vsprintf_s (стр.: TBD)
  • Стандарт C17 (ISO/IEC 9899:2018):
  • 7.21.6.8 Функция vfprintf (стр. 238)
  • 7.21.6.10 Функция vprintf (стр. 239)
  • 7.21.6.12 Функция vsnprintf (стр. 239-240)
  • 7.21.6.13 Функция vsprintf (стр. 240)
  • K.3.5.3.8 Функция vfprintf_s (стр. 434)
  • K.3.5.3.10 Функция vprintf_s (стр. 435)
  • K.3.5.3.12 Функция vsnprintf_s (стр. 436-437)
  • K.3.5.3.13 Функция vsprintf_s (стр. 437)
  • Стандарт C11 (ISO/IEC 9899:2011):
  • 7.21.6.8 Функция vfprintf (стр: 326-327)
  • 7.21.6.10 Функция vprintf (стр: 328)
  • 7.21.6.12 Функция vsnprintf (стр: 329)
  • 7.21.6.13 Функция vsprintf (стр: 329)
  • K.3.5.3.8 Функция vfprintf_s (стр: 597)
  • K.3.5.3.10 Функция vprintf_s (стр: 598-599)
  • K.3.5.3.12 Функция vsnprintf_s (стр: 600)
  • K.3.5.3.13 Функция vsprintf_s (стр: 601)
  • Стандарт C99 (ISO/IEC 9899:1999):
  • 7.19.6.8 Функция vfprintf (стр: 292)
  • 7.19.6.10 Функция vprintf (стр: 293)
  • 7.19.6.12 Функция vsnprintf (стр: 294)
  • 7.19.6.13 Функция vsprintf (стр: 295)
  • Стандарт C89/C90 (ISO/IEC 9899:1990):
  • 4.9.6.7 Функция vfprintf
  • 4.9.6.8 Функция vprintf
  • 4.9.6.9 Функция vsprintf

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

(C95) (C95) (C95) (C11) (C11) (C11) (C11)
выводит форматированный широкосимвольный вывод в stdout , файловый поток
или буфер с использованием списка переменных аргументов
(функция)
(C99) (C11) (C11) (C11) (C11)
выводит форматированный вывод в stdout , файловый поток или буфер
(функция)
(C99) (C99) (C99) (C11) (C11) (C11)
считывает форматированный ввод из stdin , файлового потока или буфера
с использованием списка переменных аргументов
(функция)
C++ documentation для vprintf , vfprintf , vsprintf , vsnprintf