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

int vwprintf( const wchar_t *format, va_list vlist );

int vwprintf( const wchar_t *restrict format, va_list vlist );

int vfwprintf( FILE* stream, const wchar_t *format, va_list vlist );

int vfwprintf( FILE *restrict stream,
               const wchar_t *restrict format, va_list vlist );

int vswprintf( wchar_t *buffer, size_t bufsz,
               const wchar_t *format, va_list vlist );

int vswprintf( wchar_t *restrict buffer, size_t bufsz,
               const wchar_t *restrict format, va_list vlist );

int vwprintf_s( const wchar_t *restrict format, va_list vlist);

int vfwprintf_s( FILE * restrict stream,
                 const wchar_t *restrict format, va_list vlist);

int vswprintf_s( wchar_t *restrict buffer, rsize_t bufsz, 
                 const wchar_t * restrict format, va_list vlist);

int vsnwprintf_s( wchar_t *restrict buffer, rsize_t bufsz,
                  const wchar_t *restrict format, va_list vlist);

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

Параметры

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

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

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

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

Не-число преобразуется в nan или nan(char_sequence). Выбор конкретного значения определяется реализацией.

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

Несмотря на то, что %c ожидает аргумент int, безопасно передавать char, из-за повышения целых чисел, которое происходит при вызове вариативной функции.

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

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

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

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

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

Примечания

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

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

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

Пример

#include <stdio.h>
#include <time.h>
#include <locale.h>
#include <stdarg.h>
#include <stddef.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

Ссылки

• Стандарт 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)

См. также