Printf

Материал из Википедии — свободной энциклопедии

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

В общем случае так называют целое семейство функций, различающихся по месту вывода (fprintf записывает вывод в файл, sprintf помещает вывод в строку), по методу передачи аргументов (vprintf принимает аргументы с помощью va_list), по дополнительным ограничениям (snprintf, vsnprintf имеют дополнительный параметр, ограничивающий максимальный размер строки).

Впервые функция появилась в предшественниках языка Си (BCPL и Би ), однако полную свою форму (с флагами, шириной, точностью и размером) она обрела в стандартной библиотеке Си, откуда попала в Си++ и Object C.

Синтаксис строки шаблона вывода (называемая иногда строкой форматирования или строкой формата) в дальнейшем начал использоваться другими языками программирования (с учётом возможных изменений в рамках возможностей языка). Помимо Си и Cи++ схожий синтаксис для строки форматирования используют Python ^[1], PHP^[2] Java ^[3], Ruby ^[4], GNU Octave^[5] Maple (встроенный язык)^[6], AMPL^[7]. Помимо этого, благодаря наличию утилиты printf в составе большинства UNIX-подобных систем, printf используется во многих shell-скриптах (для sh, bash, csh, zsh и т.д.).

[править] История появления

Первые следы будущей функции printf появляются в языке BCPL в начале 1960ых. Функция WRITEF принимает строку форматирования, в которой тип данных указывается отдельно от самих данных в строковой переменной (тип указывался без полей флагов, ширины, точности и размера, но уже предварялся символом процента %)^[8]. Появившийся вслед за ним в 1966 язык Би уже использовал название printf с простейшей строкой форматирования (указывался только один из трёх возможных типов и два представления числа: десятичные (%d), восьмеричные (%o), строки (%s) и символы (%c))^[9].

[править] Именование функций семейста

Все функции имеют в имени основу printf. Префиксы перед именем функции означают:

• w, перед остальными префиксами (wsnprintf, wvsnprintf) — использующийся фирмой Microsoft префикс для реализаций семейства функций sprintf в операционных системах Windows.
• w, после остальных префиксов (fwprintf, swprintf, wprintf) — функция использует многобайтовую кодировку (wchar_t) вместо обычных строк. (при этом функция swprintf не имеет префикса 'n', хотя и принимает параметр, ограничивающий размер результирующей строки).
• v (vprintf, vsnprintf и т.д.) — фунция вместо переменного числа параметров принимает список аргументов va_list.
• f (fprintf, vfprintf) — вывод результата в файл вместо стандартного вывода.
• s (sprintf, snprintf, vsprintf, vspnprintf) — запись результирующей строки в другую строку.
• n (snprintf, vnsprintf) — наличие параметра, ограничивающего максимальное количество символов для записи результата (используется только вместе с префиксом s).
• a (asprintf, vasprintf) — расширения GNU; функции аналогичные sprintf/vsprintf, но выделяющие достаточный объём памяти с помощью malloc для форматированной строки. Вместо указателя на строку эти функции принимают указатель на указатель на строку, освобождение памяти производит вызвавшая функция.

[править] Общие соглашения

Все функции в качестве одного из параметров (format) принимают строку форматирования (описание синтаксиса строки чуть ниже). Возвращают количество записанных (выведенных) символов, не включая нулевой символ в конце. Количество аргументов, содержащих данные для форматированного вывода, должно быть не менее, чем упомянуто в строке форматирования. «Лишние» аргументы игнорируются.

Функции семейста n (snprintf, vsnprintf) возвращают количество символов, которое было бы выведено, если бы параметр n (ограничивающий количество выводимых символов) был достаточно большим. В случае однобайтовых кодировок, возвращаемое значение соответствует необходимому размеру строки (не включая нулевой символ в конце).

Функции семейства s (sprintf, snprintf, vsprintf, vsnprintf) первым параметром (s) принимают указатель на область памяти, куда будет записана результирующая строка. Функции, не имеющие ограничения по количеству записываемых символов являются опасными функциями, т.к. могут привести к ошибке переполнения буфера, в случае, если выводимая строка окажется больше, чем размер выделенной для вывода области памяти.

Функции семейства f записывают строку в любой открытый файловый поток (параметр stream), в частности, в стандартные потоки вывода (stdout, stderr). fprintf(stdout, format, ...) эквивалентно printf(format, ...).

Функции семейства v принимают аргументы не в виде переменного числа аргументов (как все остальные printf-функции), а в виде списка va_list. При этом при вызове функции макрос va_end не выполняется.

Функции семейства w (первым символом) являются ограниченной реализацией Microsoft семейства функций s: wsprintf, wsnprintf, wvsprintf, wvsnprintf. Эти функции реализованы в динамических библиотеках user32.dll и shlwapi.dll (n функции). Они не поддерживают вывод значений с плавающей запятой, кроме того, wsnprintf и wvsnprint поддерживают выравнивание текста только по левому краю.

Функции семейства w (wprintf, swprintf) реализуют поддержку многобайтовых кодировок, все функции этого семейства работают с указателями на многобайтные строки (wchar_t).

Функции семейста a (asprintf, avsprintf) выделяют память для строки вывода при помощи функции malloc, освобождение памяти производится в вызвавшей процедуре, в случае ошибки при выполнении функции память не выделяется.

[править] Описание функций

[править] Имена параметров

• format — строка форматирования (формат описан ниже)
• stream — файловый поток для вывода
• s — строка для помещения результата работы функции
• n — переменная, содержащая максимальное допустимое количество символов для строки s
• ap — список значений для вывода
• strp — указатель на указатель на строку для помещения результатов работы функции

[править] Описание функций

• int printf( const char *format, ... );

  Вывод форматированной строки на стандартный вывод

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

  Вывод форматированной строки в поток

• int sprintf( char *s, const char *format, ... );

  Запись форматированной строки в строку без ограничения по размеру строки

• int snprintf( char *s, size_t n, const char *format, ... );

  Запись форматированной строки в строку с ограничением по размеру строки

• int vprintf( const char *format, va_list ap );

  Вывод форматированной строки на стандартный вывод, значения для вывода передаются в функцию в виде списка va_list

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

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

• int vsprintf( char *s, const char *format, va_list ap );

  Запись форматированной строки в строку без ограничения размера; значения для вывода передаются в функцию в виде списка va_list

• int vsnprintf( char *s, size_t n, const char *format, va_list ap );

  Запись форматированной строки в строку с ограничением на количество выводимых символов. Значения для вывода передаются в функцию в виде списка va_list

• int fwprintf(FILE *stream, const wchar_t *format, ... );

  Запись форматированной строки многобайтовых символов в файл

• int swprintf(wchar_t *ws, size_t n, const wchar_t *format, ... );

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

• int wprintf(const wchar_t *format, ... );

  Вывод многобайтовой форматированной строки на терминал

• int wsprintf( LPTSTR s, LPCTSTR format, ... );

  Реализация функции sprintf в операционной системе Windows. В отличие от sprintf не поддерживает вывод значений с плавающей запятой, вывод указателей, дополнительно поддерживает обработку многобайтовых строк в однобайтовой версии функции), не поддерживает флаг '+'.

• int wsnprintf( LPTSTR s, int n, LPCTSTR format, ... );

  Реализация функции snprintf в операционной системе Windows. Не поддерживает вывод значений с плавающей запятой и указателей, поддерживает только флаг выравнивания по левому краю.

• int wvsprintf( LPTSTR s, LPCTSTR format, va_list ap );
• int wvsnprintf( LPTSTR s, int n, LPCTSTR format, va_list ap );
• int asprintf(char **strp, const char *format, ... );

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

• int vasprintf(char **strp, const char *format, va_list ap);

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

Возвращаемое значение: отрицательное значение - признак ошибки; в случае успеха функции возвращают количество записанных/выведенных байтов (без учёта нулевого байта в конце), функция snprintf выводит количество байт, которые были бы записаны, если бы n было бы достаточного размера.

При вызове snprintf, n может быть равно нулю (в этом случае s может быть нулевым указателем), в этом случае запись не производится, функция только возвращает правильное возвращаемое значение.

[править] Утилита printf

В рамках стандарта POSIX описана утилита printf, которая выполняет действия, аналогичные функции printf(). Работа утилиты зависит от переменных окружения: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, LC_NUMERIC, NLSPATH.

Утилита имеет следующий формат вызова:

printf format [argument...], где

• format - строка формата, по синтаксису похожая на строку формата функции printf.
• argument - список аргументов (0 или более), записанных в строковой форме.

[править] Синтаксис строки форматирования

пример вызова printf с комментариями

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

[править] Структура управляющей последовательности

%[флаги][ширина][.точность][размер]тип
Обязательными полями являются символ начала управляющей последовательности (%) и тип.

[править] Флаги

• - (знак минуса; точнее, дефиса, ASCII код 45) — выводимое значние выравнивается по левому краю в пределах минимальной ширины поля (если флаг не указан — по правому)
• + (знак плюса) — всегда указывать знак (плюс или минус) для выводимого десятичного числового значения (если флаг не указан, то знак выводится только для отрицательных чисел)
• (пробел) — помещать перед результатом пробел, если первый символ значения не знак. + имеет больший приоритет, чем пробел. Используется только для десятичных числовых значений.
• # (октоторп) — «альтернативная форма» вывода значения.
• 0 (символ нуля) — дополнять поле символом 0 до ширины, указанной в поле ширина управляющей последовательности. Символ '-' имеет больший приоритет, чем 0. Используется для типов d, i, o, u, x, X, a, A, e, E, f, F, g, G. Для типов d, i, o, u, x, X, если точность указана, этот флаг игнорируется. Для остальных типов поведение не определено.

[править] Ширина

Ширина (десячитное число или символ звёздочка) указывает минимальную ширину поля (включая знак для чисел). Если представление величины больше, чем ширина поля, то запись выходит за пределы поля (например, %2i для величины 100 даст значение поля в три символа), если представление величины менее указанного числа, то оно будет дополнено, по-умолчанию, пробелами справа, поведение может меняться предшествующими флагами. Если в качестве ширины указана звёздочка, ширина поля указывается в списке аргументов перед значением для вывода (например, printf( "%0*5x", 8, 15 ); выведет текст 0000000f).

[править] Точность

Точность:

• указывает на минимальное количество символов, которое должно появиться при обработке типов d, i, o, u, x, X;
• указывает на минимальное количество символов, которое должно появиться после десятичной запятой (точки) при обработке типов a, A, e, E, f, F;
• максимальное количество значащих символов для типов g и G;
• максимальное число символов, которые будут выведены для типа s;

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

Если после точки указан символ "звёздочка", то при обработке строки форматирования значение для поля читается из списка аргументов. (При этом, если символ звёздочка и в поле ширины и в поле точности, сначала указывается ширина, потом точность и лишь потом значение для вывода). Например, printf( "%0*.*f", 8, 4, 2.5 ); выведет текст 002.5000.

[править] размер

Поле размер позволяет уточнить размер данных, переданных функции. Необходимость в этом поле объясняется особенностями передачи произвольного количества параметров в функцию в языке Си: функция не может "самостоятельно" определить тип и размер переданных данных, так что информация о типе параметров и точном их размере должна передаваться явно. С каждым типом ассоциирован свой размер (например, %i - 4 байта на 32 разрядных системах), а модификатор размера позволяет указать иной размер (например, %hi - 2 байта на 32 разрядных платформах).

Влияние размера на целочисленные типы данных:

• Для чисел с плавающей запятой (a, A, e, E, f, F, g, G) есть единственный модификатор: L: он указывает, что аргумент имеет тип long double.
• значение l поля размер для типа "символ" (%c) указывает на размер символа wint_t (многобайтовый символ), для типа "строка" (%s) указывает на многобайтовую строку (тип: *wchar_t)

[править] Тип

Тип указывает не только на тип величины (с точки зрения языка программирования Си), но и на конкретное представление выводимой величины (например, числа могут выводить в десятичном или шестнадцатиричном виде). Записывается в виде одного символа. В отличие от остальных полей является обязательным. Максимальный поддерживаемый по стандартам размер вывода от единичной управляющей последовательности составляет 4095 символов; на практике большинство компиляторов поддерживают существенно большие объёмы данных.

Значения типов:

• d, i — десятичное знаковое число, размер по-умолчанию, sizeof( int ). По-умолчанию записывается с правым выравниванием, знак пишется только для отрицательных чисел;
• o — восьмеричное беззнаковое число, размер по-умолчанию sizeof( int );
• u — десятичное беззнаковое число, размер по-умолчанию sizeof( int );
• x и X — шестнадцатиричное число, x использует маленькие буквы (abcdef), X большие (ABCDEF), размер по-умолчанию sizeof( int );
• f и F — числа с плавающей запятой. По-умолчанию выводятся с точностью 6, если число по модулю меньше единицы, перед десятичной точкой пишется 0. Величины ±∞ представляются в форме [-]inf или [-]infinity, Величина Nan представляется как [-]nan или [-]nan(любой текст далее). Использование F выводит указанные величины заглавными буквами (-INF, NAN). Аргумент по-умолчанию имеет размер double.
• e и E — числа с плавающей запятой в экспоненциальной форме записи (вида 1.1e+44); e выводит символ 'e' в нижнем регистре, E — в верхнем (3.14E+0);
• g и G — число с плавающей запятой; форма представления зависит от значения величины (f или e);
• a и A — число с плавающей запятой в шестнадцатиричном виде;
• c — вывод символа с кодом, соответствующим переданному аргументу; переданное число приводится к типу usnigned char (или wint_t, если был указан модификатор длины l);
• s — вывод строки с нулевым завершающим байтом; если модификатор длины - l, выводится строка wchar_t*;
• p — вывод указателя, внешний вид может существенно различаться в зависимости от внутреннего представления в компиляторе и платформе (например, 16 битная платформа MS-DOS использует форму записи вида FFEC:1003, 32-битная платформа с плоской адресацией использует адрес вида 00FA0030);
• n — запись по указателю, переданному в качестве аргумента количество символов, записанных на момент появления командной последовательности, содержащей n;
• % — символ для вывода знака процента (%), используется для возможности вывода символов процента в строке printf, всегда используется в виде %%.

[править] Вывод чисел с плавающей запятой

В зависимости от текущей локали, при выводе чисел с плавающей запятой может использоваться как запятая, так и точка (а, возможно, и другой символ). Поведение printf в отношении разделяющего дробную и целую часть числа символа определяется переменной LC_NUMERIC^[10]

[править] XSI расширения в стандарте Single Unix

В рамках стандарта Single UNIX (практически эквивалентного стандарту POSIX), определены следующие дополнения printf по отношению к ISO C, в рамках расширения XSI (X/Open System Interface):

• Добавляется возможность вывода произвольного по номеру параметра (указывается в виде n$ сразу после символа начала управляющей последовательности, например, printf("%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec);).
• Добавлен флаг «'» (одинарная кавычка), который для типов d, i, o, u предписывает разделять классы соответствующим символом.
• тип C, эквивалентный lc ISO C (вывод символа типа wint_t).
• тип S, эквивалентный ls ISO C (вывод строки типа wchar_t*)
• Добавлены коды ошибок EILSEQ, EINVAL, ENOMEM, EOVERFLOW.

[править] Нестандартные расширения

[править] GNU C Library

В рамках GNU C Library (libc) добавлены следующие расширения:

• тип m выводит значение глобальной переменной errno (код ошибки последней функции).
• тип C эквивалентен lc.
• флаг ' (одинарная кавычка) используется для разделения классов при выводе чисел. Формат разделения зависит от LC_NUMERIC
• размер q указывает на тип long long int (на системах, где не поддерживается тип long long int, это то же самое, что и long int
• размер Z является алиасом для z, был введён в libc до появления стандарта C99, не рекомендуется к использованию в новом коде.

[править] Регистрация собственных типов

GNU libc поддерживает регистрацию пользовательских типов, позволяя программисту определять формат вывода для собственных структур данных. Для регистрации нового типа используется функция
int register_printf_function (int type, printf_function handler-function, printf_arginfo_function arginfo-function), где:

• type — буква для типа (если type = 'Y', то вызов будет выглядеть как '%Y');
• handler-function — указатель на функцию, которая вызывается, printf-функциями, если в строке форматирования встречается тип, указанный в type;
• arginfo-function — указатель на фунцию, которая будет вызываться функцией parse_printf_format.

Помимо определения новых типов регистрация позволяет переопределить существующие типы (такие, как s, i).

[править] Microsoft Visual C

В составе Microsoft Visual Studio для языков программирования Cи/Cи++ в формате спецификации printf (и остальных функций семейста) предусмотрены следующие расширения:

• поле размера:

[править] Уязвимости

Функции семейста printf принимают список аргументов и их размер отдельным параметром (в строке форматирования). Несоответствие строки форматирования и переданных аргументов может приводить к непредсказуемому поведению, повреждению стека и выполнению произвольного кода, приводить к разрушению областей динамической памяти. Многие функции называются "небезопасными" (англ. unsafe), т.к. не имеют даже теоретической возможности для защиты от некорректных данных.

Так же функции семейства s (без n, такие как sprintf, vsprintf) не имеют ограничителей по максимальному размеру записываемой строки и могут приводить к ошибке переполнения буффера (когда данные записываются за пределы отведённой области памяти).

[править] Поведение при несоответствии строки форматирования и переданных аргументов

[править] Уязвимость строки форматирования

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

Пример некорректного кода:
printf(" Current status: 99% stored.");
В этом примере содержится управляющая последовательность "% s", содержащая признак управляющей последовательности (%), флаг (пробел) и тип данных "строка" (s). Функция, приняв управляющую последовательность, попытается прочитать с стека указатель на строку. Т.к. в функцию не передавались дополнительные параметры, значение, которое будет прочитано со стека не определено. Полученное значение будет интерпретировано как указатель на строку с завершающим нулём. Вывод такой "строки" может привести к выводу произвольного дампа памяти, ошибке доступа к памяти и разрушению стека. Такой тип уязвимости называют атакой на строку форматирования (англ. Format string attack)^[11].

[править] Сложности в использовании

Функции семейства printf используют типы данных языка Си, размер типов, и соотношение размеров типов может меняться от платформы к платформе (например, на 64-битных платформах в зависимости от выбранной модели (LP64, LLP64 или ILP64) размеры типов int и long могут различаться). При этом "правильно" работавший код на одной платформе начинает выдавать неправильный результат на другой (в ряде случаев, возможно, приводя к повреждению данных).

Например, код printf( "end address: 0x%X", "text line" ); работает правильно на 32-битной платформе (размер ptrdiff_t и размер int 32 бита) и на 64-битной модели IPL64 (где размеры ptrdiff_t и int 64 бита), но даст неверный результат на 64-битной платформе модели LP64 или LLP64, где размер ptrdiff_t 64 бита, а размер int 32 бита ^[12].

[править] printf в других языках программирования

[править] Ссылки

1. ↑ Описание форматирующего оператора для строковых типов в питоне [1]
2. ↑ Описание функции printf в составе PHP [2]
3. ↑ Начиная с версии 1.5, в Java имеется функция java.io.PrintStream.printf() (доступная, в частности, через стандартные переменные System.out и System.err). Она подобна функциональностью классу java.text.MessageFormat, но использует другой, схожий с Си, синтаксис строки формата.
4. ↑ Описание функции printf в документации Ruby [3]
5. ↑ Описание шаблона строки для printf в документации GNU Octave [4]
6. ↑ Описание printf в документации к Mapple^{[Источник?]}
7. ↑ R. Fourer, D.M. Gay, and B.W. Kernighan. AMPL: A Modeling Language for Mathematical Programming, 2nd Ed.. Pacific Grove, CA: Brooks/Cole--Thomson Learning, 2003.
8. ↑ Краткое описание языка BCPL [5]
9. ↑ Руководство по языку Би [6]
10. ↑ §7.11.1.1 ISO/IEC 9899:TC2, LC_NUMERIC определяет, в частности, форму представления разделителя дробной и целой части.
11. ↑ Описание уязвимостей printf, Robert C. Seacord: Secure Coding in C and C++. Addison Wesley, September, 2005. ISBN 0-321-33572-4
12. ↑ Описание проблем переноса приложений с 32 на 64 битную архитектуру. [7]

[править] Источники

• printf, fprintf, snprintf, vfprintf, vprintf, vsnprintf, vsprintf в стандарте ISO/IEC 9899:TC2 (ISO C) [8]
• printf, fprintf, sprintf, snprintf в стандарте Single Unix [9]
• vprintf, vfprintf, vsprintf, vsnprintf в стандарте POSIX [10]
• wprintf, swprintf, wprintf в стандарте POSIX [11]
• vfwprintf, vswprintf, vwprintf в стандарте POSIX [12]
• wsprintf в MSDN [13]
• wvnsprintf в MSDN [14]
• wnsprintf в MSDN [15]
• wvsprintf в MSDN [16]
• wnsprintf в MSDN [17]
• asprintf, vasprintf в man-pages в Linux [18], в документации к libc [19]
• Описание синтакисиса строки форматирования в руководстве libc [20].
• Описание строки форматирования в документации к Microsoft Visual Studio 2005 [21]
• Описание register_printf_function [22], [23]

[править] См также

• Си
• scanf
• Стандартная библиотека