Spec-Zone.ru › C

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

Определено в заголовочном файле <wchar.h> 
int vwprintf( const wchar_t* format, va_list vlist );
(1) (начиная с C95)
(до C99) 
int vwprintf( const wchar_t* restrict format, va_list vlist );
(начиная с C99) 
int vfwprintf( FILE* stream, const wchar_t* format, va_list vlist );
(2) (начиная с C95)
(до C99) 
int vfwprintf( FILE* restrict stream,
               const wchar_t* restrict format, va_list vlist );
(начиная с C99) 
int vswprintf( wchar_t* buffer, size_t bufsz,
               const wchar_t* format, va_list vlist );
(3) (начиная с 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 - список переменных аргументов, содержащий данные для печати.


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

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

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

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

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

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

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

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

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

  • Точность задаёт минимальное число выводимых цифр. Точность по умолчанию — 1.
  • Если и преобразованное значение, и точность равны 0, результатом преобразования не будет ни одного символа.
  • Для модификатора z ожидаемый тип аргумента — знаковый вариант size_t.
signedchar
short
int
long
longlong
intmax_t
※
ptrdiff_t
 Н/Д
b
B (необязательно)

(C23)

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

  • Точность задаёт минимальное число выводимых цифр. Точность по умолчанию — 1.
  • Если и преобразованное значение, и точность равны 0, результатом преобразования не будет ни одного символа.
  • При альтернативной реализации перед результатом, если преобразованное значение не равно нулю, добавляется 0b или 0B.
unsignedchar
unsignedshort
unsignedint
unsignedlong
unsignedlonglong
uintmax_t
size_t
беззнаковый вариант ptrdiff_t
Н/Д
o

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

  • Точность задаёт минимальное число выводимых цифр. Точность по умолчанию — 1.
  • Если и преобразованное значение, и точность равны 0, результатом преобразования не будет ни одного символа.
  • При альтернативной реализации точность при необходимости увеличивается, чтобы вывести один ведущий ноль. В этом случае, если и преобразованное значение, и точность равны 0, выводится один символ 0.
 Н/Д
x
X

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

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

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

  • Точность задаёт минимальное число выводимых цифр.
  • Точность по умолчанию — 1.
  • Если и преобразованное значение, и точность равны 0, результатом преобразования не будет ни одного символа.
 Н/Д
f
F (C99)

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

  • Точность задаёт точное число цифр после символа десятичной точки.
  • Точность по умолчанию — 6.
  • При альтернативной реализации символ десятичной точки выводится, даже если за ним нет цифр.
  • О преобразовании бесконечности и «не числа» см. примечания.
 Н/Д Н/Д
double
double (C99)
Н/Д Н/Д Н/Д Н/Д
longdouble
e
E

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

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

(C99)

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

  • Для преобразования с a используется формат [-] 0xh.hhh p±d.
  • Для преобразования с A используется формат [-] 0Xh.hhh P±d.
  • Первая шестнадцатеричная цифра не 0, если аргумент является нормализованным числом с плавающей запятой.
  • Если значение равно 0, экспонента также 0.
  • Точность задаёт точное число цифр после символа шестнадцатеричной точки.
  • Точность по умолчанию достаточна для точного представления значения.
  • При альтернативной реализации символ десятичной точки выводится, даже если за ним нет цифр.
  • О преобразовании бесконечности и «не числа» см. примечания.
 Н/Д Н/Д Н/Д Н/Д Н/Д Н/Д
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.
signedchar*
short*
int*
long*
longlong*
intmax_t*
※
ptrdiff_t*
Н/Д
p

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

 Н/Д Н/Д
void*
Н/Д Н/Д Н/Д Н/Д Н/Д Н/Д
Примечания

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

«Не число» преобразуется в nan или nan(char_sequence). Используемый вариант определяется реализацией.

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

Спецификатор преобразования, используемый для вывода char, unsignedchar, signedchar, short и unsignedshort, ожидает типы, полученные в результате стандартных целочисленных повышений аргументов, но перед выводом значение преобразуется в char, unsignedchar, signedchar, short и unsignedshort. Передавать значения этих типов безопасно благодаря повышению, выполняемому при вызове функции с переменным числом аргументов.

Корректные спецификаторы преобразования для целочисленных типов фиксированной ширины (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)

См. также

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

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/c/io/vfwprintf

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API