printf()

Печать в стандартный поток вывода (stdout)

Прототип:

#include <stdio.h>
int printf( const char *format,
... );

Аргументы:

format
Строка, управляющая форматом вывода. Определяет, дополнительные аргументы необходимо передать функции.

Библиотека:

libc

Описание:

Функция printf() направляет печать символов в стандартынй поток вывода stdout, согласно спецификатору формата.


Note: Если строка формата содержит недопустимые многобайтовые символы, обработка останавливается, и выводится оставшаяся часть форматной строки, включая символы %. Это может произойти, например, если были указаны международные символы и знаки, использующие ISO 8859-1 вместо UTF-8. При вызове:

setlocale( LC_CTYPE, "C-TRADITIONAL" );

перед вызовом printf() локаль переключает многобайтовую обработку с UTF-8 на 1-к-1, а printf() корректно передает неправильно сформированные многобайтовые символы.


Аргументы формата

Если после обработки format остались неучтенные аргументы, они игнорируются.

Семейство функций printf() позволяет использовать символы системы счисления, зависящие от языка. Символ по умолчанию — «.», он управляется LC_NUMERIC и setlocale().

Управление форматом

Строка управления форматом состоит из:

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

Флаги управления форматом

Допустимые флаги управления форматом:

-
выравнивание по левому краю отформатированного элемента в поле вывода; обычно элементы выравниваются по правому краю.
+
Отображать знак плюс (+) в начале у положительных объектов; обычно только у отрицательных элементов отображается знак в начале.
space
Положительные объекты начинаются со знака пробела; если указаны и +, и пробел, используется +.
#
Использовать альтернативную форму преобразования:
0 (zero)
Преобразуемое значение слева дополняется нулями (вместо пробелов) для d, i, o, u, x, X, e, E, f, g и G преобразований. Флаг «-» переопределяет этот флаг.

Ширина поля

Если не была указана ширина поля или заданное значение меньше числа символов в преобразованном значении (с учетом любого значения точности), используется поле достаточной ширины, чтобы содержать преобразованное значение.

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

Если ширина поля равна * (или 0*), значение типа int из списка аргументов используется (перед аргументом точности или аргументом преобразования) в качестве минимальной ширины поля. Отрицательное значение ширины поля интерпретируется как флаг выравнивания по левому краю, за которым следует положительное значение ширины поля.

Спецификатор точности

Как и в случае со спецификатором ширины поля, спецификатор точности * приводит к использованию значения типа int из списка аргументов в качестве спецификатора точности. Если был задан спецификатор точности *, но в списке аргументов нет значения точности, используется точность 0.

Значение точности влияет на следующие преобразования:

Спецификатор длины типа

Спецификатор длины типа влияет на преобразование следующим образом:

Спецификаторы типа преобразования

Допустимые спецификаторы типа преобразования:

a, A
Преобразует аргумент типа double в стиль [-]0xh.hhhh p1d, где перед десятичной точкой стоит одна ненулевая шестнадцатеричная цифра. Количество шестнадцатеричных цифр после запятой равно точности. Если точность не задана, а FLT_RADIX является степенью 2, то точность достаточна для представления. Если точность равна нулю и не был указан флаг #, десятичная точка не отображается. Преобразование a использует буквы abcdef и производит преобразование x и p; преобразование A в ABCDEF, X и P. Показатель степени всегда имеет одну цифру, даже если это 0, и не больше цифр, чем необходимо. Значения бесконечности или NaN преобразуются в стиле f или F.
c
Преобразование аргумента типа int в значение типа unsigned char и запись соответствующего кода символа ASCII в поток вывода. Квалификатор l приводит к преобразованию аргумента wint_t, как если бы посредством преобразования ls в wchar_t, где первым элементом является wint_t, а вторым является символ нулевой ширины.
d, i
Преобразует аргумент типа int в десятичную запись со знаком и записывает его в поток вывода. Точность по умолчанию — 1, но если требуется больше цифр, добавляются нули в начале.
e, E
Преобразует аргумент типа double в десятичную запись вида [-]d.ddde[+|-]dd. Начальный знак появляется (с учетом флагов управления форматом) только в том случае, если аргумент отрицательный. Если аргумент не равен нулю, цифра перед символом десятичной точки не равна нулю. Точность используется как количество цифр после символа десятичной точки. Если точность не указана, используется точность по умолчанию, равная шести. Если точность равна 0, символ десятичной точки подавляется. Значение округляется до соответствующего количества цифр. Знак экспоненты и показатель степени (указывающий степень десяти, на которую умножается десятичная дробь) выводятся всегда. Показатель степени имеет длину не менее двух цифр и имеет столько дополнительных цифр, сколько необходимо для его представления. Если значение равно нулю, показатель степени равен нулю. Для преобразования E показатель степени начинается с символа E, а не с e. Аргументы бесконечности или NaN преобразуются в стиле спецификаторов преобразования f или F.
f, F
Преобразует аргумент типа double в десятичную запись в форме [-]ddd.ddd с количеством цифр после запятой, равным спецификатору точности. Начальный знак появляется (с учетом флагов управления форматом) только в том случае, если аргумент отрицательный. Точность используется как количество цифр после символа десятичной точки. Если точность не указана, используется точность по умолчанию, равная шести. Если точность равна 0, символ десятичной точки подавляется; в противном случае перед символом десятичной точки выводится по крайней мере одна цифра. Значение округляется до соответствующего количества цифр. Аргумент типа double, представляющий бесконечность или NaN, преобразуется в [-]inf или [-]nan. Спецификатор F преобразуется [-]INF или [-]NAN.
g, G
Преобразование аргумента типа double с использованием стиля преобразования e или f (или E для преобразования G), в зависимости от значения аргумента. В любом из случаев точность определяет количество значащих цифр, содержащихся в результате. Преобразование в стиле e используется только в том случае, если показатель степени такого преобразования будет меньше, чем -4, или больше, чем точность. Нули в конце удаляются из результата, а символ десятичной точки появляется только в том случае, если за ним следует цифра. Аргументы, представляющие бесконечность или NaN, преобразуются в стиле спецификаторов преобразования f или F.
n
Определяет количество символов, записанных в поток вывода, для целого числа, на который указывает аргумент. Вывод не производится.
o
Преобразование аргумента типа unsigned в восьмеричное представление без знака и запись его в поток вывода. Точность по умолчанию — 1, но если требуется больше цифр, добавляются нули в начале.
p
Преобразование аргумента типа void * в значение типа int и форматирование значения как для шестнадцатеричного (x) преобразования.
s
Записать символы из строки, заданной аргументом типа char *, вплоть до завершающего символа NUL ('\0'), но не включая его, в поток вывода. Если указана точность, то будет записано не более указанного количества символов. Если используется квалификатор l, аргумент интерпретируется как указатель на массив wchar_t, и каждый символ, включая завершающий NUL, преобразуется, как если бы он был вызван вызовом wcrtomb(). Завершающий NUL пишется только в том случае, если точность не указана или если точность указана, а длина последовательности символов меньше точности.
u
Преобразует аргумент типа unsigned в беззнаковую десятичную запись и записывает его в поток вывода. Точность по умолчанию — 1, но если требуется больше цифр, добавляются нули в начале.
x, X
Преобразование аргумента типа unsigned в шестнадцатеричное представление без знака и запись его в поток вывода. Точность по умолчанию — 1, но если требуется больше цифр, добавляются нули в начале. Шестнадцатеричная запись использует цифры от 0 до 9 и символы от a до f или от A до F для преобразования x или X, соответственно, в качестве шестнадцатеричных цифр. В зависимости от контрольного флага перед выводом добавляется 0x или 0X.
%
Напечатать символ % (%% для полной спецификации).

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

Аргументы должны соответствовать спецификаторам типа преобразования слева направо в строке; в противном случае будут получены неопределенные результаты.

Если значение, соответствующее спецификатору с плавающей запятой, равно бесконечности или не является числом (NAN), тогда вывод будет inf или -inf для бесконечности и nan или -nan для NAN.

Например, спецификатор формы %8.*f определяет поле шириной не менее 8 символов и получает следующий аргумент для точности, которая будет использоваться при преобразовании.

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

>=0
Число записанных байт без завершающего NULL
<0
Возникла ошибка. Код ошибки записан в errno.

Примеры:

#include <stdio.h>
#include <stdlib.h>
int main( void )
{
char *weekday, *month;
weekday = "Saturday";
month = "April";
printf( "%s, %s %d, %d\n", weekday, month, 10, 1999 );
printf( "f1 = %8.4f f2 = %10.2E x = %#08x i = %d\n",
23.45, 3141.5926, 0x1db, -1 );
return (EXIT_SUCCESS);
}

Код генерирует следующий вывод:

$ ./a.out Saturday, April 10, 1999 f1 = 23.4500 f2 = 3.14E+003 x = 0x0001db i = -1

Классификация:

ANSI, POSIX 1003.1

Точка остановки потока
Да
Обработчик прерываний
Нет
Обработчик сигналов
Нет
В потоке
Да

Тематические ссылки:

errno, fprintf(), fwprintf(), snprintf(), sprintf(), swprintf(), vfprintf(), vfwprintf(), vprintf(), vsnprintf(), vsprintf(), vswprintf(), vwprintf(), wprintf()




Предыдущий раздел: Описание API системной библиотеки