PRINTF(3S)

НАЗВАНИЕ

printf, fprintf, sprintf, snprintf, asprintf, vprintf, vfprintf, vsprintf, vsnprintf, vasprintf - вывод с преобразованием по формату

СИНТАКСИС

#include <stdio.h>

int printf (format, val ...) char *format;

int fprintf (stream, format, val ...) FILE *stream; char *format;

int sprintf (s, format [, val] ...) char *s, *format;

int snprintf(char *str, size_tsize, const char *format, ...)

int asprintf(char **ret, const char *format, ...)

#include <stdarg.h>

int vprintf(const char *format, va_list ap)

int vfprintf(FILE *stream, const char *format, va_list ap)

int vsprintf(char *str, char *format, va_list ap)

int vsnprintf(char *str, size_t size, const char *format, va_list ap)

int vasprintf(char **ret, const char *format, va_list ap)

ОПИСАНИЕ

Функция printf направляет данные в стандартный поток вывода stdin. Функция fprintf направляет данные в поток вывода, заданный аргументом stream. Функция sprintf направляет данные, заканчивающиеся пустым символом (\0), в массив s; пользователь должен позаботиться о выделении достаточного количества памяти для массива. Каждая функция возвращает число переданных символов (не считая пустого в случае sprintf), или отрицательное число, если при выводе обнаружилась ошибка.

Каждая из перечисленных функций преобразует, форматирует и печатает выводимые значения val под управлением формата, заданного аргументом format. Формат - это цепочка символов, содержащая об екты двух категорий: обычные символы, которые просто копируются в выходной поток, и спецификаторы преобразований, каждому из которых соответствует одно, несколько или ни одного из выводимых значений. Если выводимых значений val недостаточно, результат непредсказуем; если их слишком много, избыточные игнорируются.

Каждый спецификатор преобразования начинается символом %, после которого последовательно записываются:

Флаги (один, несколько или ни одного), которые уточняют смысл спецификации преобразования.
Необязательная последовательность десятичных цифр, задающая минимальную ширину поля, в котором изображается результат преобразования. Если результат может быть изображен меньшим количеством символов, то поле дополняется слева (или справа, если задан флаг выравнивания по левой границе) пробелами до минимальной ширины; если последовательность, задающая ширину поля, начинается нулем, то для дополнения используются нули.
Точность, задающая минимальное количество цифр в изображении результата преобразования типа d, i, o, u, x, X, количество цифр после десятичной точки в изображении результата преобразования типа e, E, f, максимальное количество значащих цифр в изображении результата преобразования типа g, G, или максимальное количество символов в изображении результата преобразования типа s. Точность записывается в виде точки (.), за которой следует несколько десятичных цифр; отсутствие цифр интерпретируется как ноль. Дополнение результата символами, обусловленное точностью, подавляет дополнение, обусловленное шириной поля.
Необязательный символ l, означающий, что относящиеся к нему преобразования d, i, o, u, x, X применяются к целым выводимым значениям типа long. Для остальных преобразований символ l игнорируется.
Символ, обозначающий тип преобразования.

Вместо последовательности цифр ширину поля и точность можно обозначить звездочкой. Это означает, что в качестве ширины поля (или точности) используется целое значение val из списка аргументов; оно должно предшествовать соответствующему выводимому значению. Если значение, задающее ширину поля, отрицательно, то считается, что задан флаг -, а в качестве ширины поля берется абсолютная величина значения. Если отрицательно значение, задающее точность, она принимается равной нулю.

Флаги и их смысл: - + пробел #

Выравнивание результата преобразования по левой границе.

Обязательное изображение знака (для чисел со знаком).

Если первый символ результата преобразования со знаком отличен от + и -, то изображение результата предваряется пробелом. Тем самым флаг + аннулирует действие флага пробел.

Этот флаг означает, что значение преобразуется к "альтернативной форме". Для преобразований c, d, i, s, u этот флаг не имеет значения. Для преобразования типа o результат изображается с увеличенной точностью, с тем чтобы первая цифра результата была нулем. Для преобразований типа x, X ненулевой результат будет изображаться с префиксом 0x или 0X. Для преобразований типа e, E, f, g, G результат обязательно изобразится с десятичной точкой, даже если за ней нет цифр (обычно точка в этом случае опускается). Для преобразований g, G не подавляются незначащие хвостовые нули (что обычно делается).

Символы, обозначающие тип преобразования, и их смысл: d, i, o, u, x, X f e, E g, Gc s %

Целое выводимое значение преобразуется в десятичное со знаком (d, i), беззнаковое восьмеричное (o), десятичное (u) или шестнадцатеричное (x, X); буквы abcdef изображают шестнадцатеричные цифры при преобразовании x, а ABCDEF - при преобразовании X. Точность задает минимальное количество цифр в изображении результата; если результат можно изобразить меньшим количеством цифр, то слева добавляются незначащие нули. Значение точности по умолчанию равно 1. Результат преобразования нуля с нулевой точностью - пустая цепочка.

Выводимое значение типов float или double преобразуется в десятичное число и изображается в виде [-]ddd.ddd, где число цифр после точки определяется точностью. Если точность опущена, то считается, что она равна 6; если точность равна нулю, точка не печатается.

Выводимое значение типов float или double преобразуется в десятичное число и изображается в виде [-]d.ddde+/-dd, где перед точкой находится ровно одна цифра, а число цифр после точки определяется точностью; по умолчанию точность равна 6; если точность равна нулю, точка не печатается. Спецификация E отличается от e только обозначением порядка (E вместо e). Порядок всегда содержит по крайней мере две цифры.

Выводимое значение типов float или double преобразуется в десятичное число и изображается либо в формате f, либо в формате e (или E, если задана спецификация G); точность определяется числом значащих цифр. Вид изображения зависит от значения аргумента: вид e используется только в том случае, если порядок меньше -4 или больше значения точности. Хвостовые незначащие нули подавляются; десятичная точка печатается, только если за ней есть цифры.

Печатается значение-символ.

Выводимое значение, заданное указателем, рассматривается как цепочка символов, ограниченная пустым символом (\0); печать цепочки прекращается либо по ограничителю, либо после вывода количества символов, равного значению точности. По умолчанию точность считается бесконечно большой; в этом случае цепочка печатается до тех пор, пока не встретится ограничитель. Пустой указатель (NULL) дает непредсказуемые результаты.

Печать символа %; выводимых значений не требуется.

Содержание раздела