Книга по работе с WinAVR и AVR Studio / AVR_11-2010

Роман Абраш

Книга по работе

г. Новочеркасск

с WinAVR и AVR Studio

E-mail: arv@radioliga.com

символы перевода строки и возврата карет-

Имеется возможность связать с пото-

Продолжение.

ки следует вставлять принудительно.

ком дополнительные пользовательские дан-

Начало в №1-10/2010

Первое обращение к fdevopen() для чте-

ные при помощи fdev_set_udata(), которые

ния приведет к фактической связи с пото-

затем могут быть извлечены в реализаци-

stdio.h – Стандартный

ком stdin. Обращение же к fdevopen() на

ях функций ввода-вывода символа при по-

ввод-вывод

запись приведет к тому, что результирую-

мощи fdev_get_udata() и обработаны, как

В силу направленности avr-libc на мик-

щий поток будет связан с stdin и stderr, т.е.

требуется. Это, например, позволит реали-

роконтроллеры, т.е. на среду без операци-

фактически оба этих потока будут на самом

зовать одну функцию ввода-вывода, рабо-

онной системы и любых стандартных

деле одним (stdin и stderr в данном контек-

тающую с различными UART. В этом слу-

средств ввода-вывода, имеются большие

сте – просто синонимы). Соответственно

чае функции ввода-вывода сохраняют кон-

отличия в реализации функций модуля по

закрытие функцией fclose() любого из этих

текст различных UART в области данных

сравнению с требованиями стандарта. Ре-

потоков фактически закроет и его синоним.

пользователя между своими вызовами.

ализован только необходимый минимум

Данный подход позволил существенно оп-

По умолчанию fdevopen() подразумева-

функций. Имеется ряд условностей и огра-

тимизировать результирующий код: во-пер-

ет использование malloc(), что часто очень

ничений, связанных с аппаратной и архи-

вых, за счет исключения дублирования

нежелательно в ограниченных ресурсах

тектурной особенностью среды.

структур данных потоков; во-вторых, нет

микроконтроллера. Поэтому в библиотеке

Для максимальной компактности гене-

необходимости в функции fprintf(); в-треть-

реализован опциональный вариант

рируемого кода многие возможности усе-

их, можно отказаться от передачи через

fdevopen() без использования malloc(). Мак-

чены или исключены полностью, например,

стек лишнего параметра (указателя на ис-

рос fdev_setup_stream() позволяет настро-

касающиеся форматированного ввода-вы-

пользуемый поток). В сущности, это оправ-

ить стандартные функции ввода-вывода для

вода функциями printf() и scanf(). Часть воз-

дано особенностями архитектуры микро-

работы с подготовленным заранее буфером

можностей этих функций может быть вклю-

контроллера.

файла. Пример см. на врезке.

чена или выключена путем задания опре-

деленных опций (параметров) компилято-

Врезка. Пример:

ра, чтобы получать код минимального раз-

#include <stdio.h> // подключение модуля ввода-вывода

мера с необходимым минимумом функцио-

нальности.

static int uart_putchar(char c, FILE *stream);

// определяемая пользователем

Стандартные потоки stdin, stdout и stderr

// функция вывода символа

поддерживаются «виртуально», т.к. нет ни-

// подготовка при помощи макроса структуры «файла» для ввода-вывода

какой аппаратной их поддержки, нет и ни-

static FILE mystdout = FDEV_SETUP_STREAM(uart_putchar, NULL, _FDEV_SETUP_WRITE);

какой инициализации этих потоков; т.к. нет

// реализация функции вывода символа

реально существующих файлов вообще –

нет и fopen() и т.п. Имеется функция

static int uart_putchar(char c, FILE *stream){

// принудительная вставка символа «возврат каретки» после символа

fdevopen(), которая позволяет связать стан-

// «перевод строки» для нормального отображения в терминальной программе

дартные функции ввода-вывода с реализу-

if (c == ’\n’)

емыми программистом средствами поддер-

uart_putchar(’\r’, stream);

loop_until_bit_is_set(UCSRA, UDRE); // ожидание готовности UART

жки конкретной аппаратуры. В качестве

альтернативы можно использовать макрос

UDR = c; // вывод символа

fdev_setup_stream(), при помощи которого

return 0;

производится инициализация средств вво-

да-вывода. В любом случае программист

}

самостоятельно должен реализовать фун-

// основная функция

кцию ввода, вывода или обе только для од-

int main(void){

ного символа (нет различий между символь-

init_uart(); // инициализация UART

ным и двоичным потоками), которая затем

stdout = &mystdout; // связывание потока stdout с подготовленным «файлом»

printf(«Hello, world!\n»); // использование стандартной функции вывода

и используется для работы со стандартны-

return 0;

ми потоками. Более подробно об этом бу-

}

дет сказано далее, при рассмотрении соот-

ветствующих функций.

Приведенный пример выводит в стан-

Определения модуля

Так же с целью получения наиболее ком-

дартный поток, связанный с аппаратно-ре-

В модуле определены следующие кон-

пактного кода, имеется ряд функций, спо-

ализованным UART микроконтроллера, тек-

станты и макросы:

собных работать сразу со строковыми кон-

стовое сообщение.

стантами, определенными в сегменте кода

В примере применена инициализа-

FILE

программы.

ция потока mystdout макросом

FILE – определение структуры «файл»,

Реализация библиотеки, как было ска-

FDEV_SETUP_STREAM() вместо макроса

т.е. структуры, передаваемой в различные

зано ранее, не делает различий между тек-

fdev_setup_stream(), поэтому вся инициали-

функции ввода-вывода в качестве иденти-

стовыми и двоичными операциями ввода-

зация потока происходит в момент инициа-

фикатора файла.

вывода, поэтому следует быть осторожны-

лизации переменных С-программы, т.е. со-

ми при использовании автоматических пре-

вершенно прозрачно для пользователя.

stdin

образований, реализуемых функциями вво-

Если инициализированный таким обра-

stdin – поток, используемый упрощен-

да-вывода, например, автоматической

зом поток более не нужен, он может быть

ными (т.е. не требующими параметра

вставки символа перевода строки. Этот

разрушен макросом fdev_close(). Не требу-

stream) функциями ввода.

символ будет нарушать нормальную двоич-

ется использование fclose(), т.к. это потре-

ную последовательность, поэтому для дво-

бует от компоновщика подключения моду-

stdout

ичных потоков надо исключить любую «ав-

ля stdlib.h – Стандартные возможности для

stdout – поток, используемый упрощен-

томатику» преобразований. Если же после

«освобождения» памяти, что в данном слу-

ными (т.е. не требующими параметра

этого потребуется выводить текст в потоки,

чае совершенно лишнее.

stream) функциями вывода.

5 6

Радиолюбитель – 11/2010

stderr

ничего, но введен для совместимости с бу-

Ширина – это десятичное число, кото-

stderr – поток, используемый для вы-

дущими реализациями.

рое определяет минимальное количество

вода сообщений об ошибках. По умолчанию

символов, требуемое для представления

соответствует stdout. Если необходимо на-

putc()

числа. Если число может быть представле-

править сообщения об ошибках в другой,

putc(c, stream) – макрос «упрощенно-

но меньшим количеством символов – оно

отличный от stdout, поток, необходимо при-

го» вывода в поток, полностью аналогич-

дополняется слева или справа (в зависимо-

своить ему другое значение, возвращен-

ный (и являющийся синонимом) fputc().

сти от префикса) пробелами (или нулями –

ное fdevopen(), не закрывая имеющееся

см. префикс 0). Если для представления

(т.к. иначе это привело бы к закрытию

putchar()

числа необходимо больше символов, то зна-

stdout).

putchar(c) – макрос вывода символа в

чение ширины игнорируется. Т.е. если ука-

поток stdout.

зана ширина 3 и задан префикс 0, то число

EOF

1 будет выведено как “001”.

EOF – константа «конец файла». Это

getc()

Точность – это десятичное число, оп-

значение возвращается функциями ввода

getc(stream) – макрос «упрощенного»

ределяющее символов в представлении

в качестве индикатора ошибки. Так как в

ввода из поток, полностью аналогичный (и

для достижения заданной точности. Для

текущей реализации для AVR не существу-

являющийся синонимом) fgetc().

строковых аргументов определяет макси-

ет реального понятия «файл», иное исполь-

мальную длину строки, для числовых – ми-

зование этой константы – бессмысленно.

getchar()

нимальное кол-во значащих цифр. Пару

getchar() – макрос, возвращающий сим-

ширина-точность для чисел с плавающей

fdev_set_udata()

вол, считанный из потока stdin.

точкой можно рассматривать как пару

fdev_set_udata(stream, u) – макрос

«общее кол-во знаков»-«кол-во знаков

вставки пользовательских данных (указа-

Спецификация строки формата

после точки».

тель) u во внутреннюю структуру файла

для функций форматированного

Суффикс – это символ h или l. h – иг-

stream. Использование этих данных воз-

вывода

норируется, а l означает, что аргумент име-

можно в функциях get() и put().

Строка формата ввода-вывода состо-

ет тип long, а не int.

ит из последовательностей символов двух

Тип – это символ, который определяет

fdev_get_udata()

типов: обычных, которые копируются в по-

тип очередного элемента в списке выводи-

fdev_get_udata(stream) – макрос воз-

ток непосредственно, и последовательнос-

мых аргументов. Определены следующие

врата пользовательских данных (указате-

тей символов-директив (или управляющих

типы (должен указываться любой из пере-

ля) из внутренней структуры файла stream.

символов), которые в процессе обработки

численных):

заменяются другими в соответствии с оп-

diouxX – целое число. Аргумент рас-

fdev_setup_stream()

ределенными правилами. Формат управля-

сматривается, как целое число, и выводит-

fdev_setup_stream(stream, put, get,

ющей последовательности следующий (в

ся в десятичном со знаком(di), десятичном

rwflag) – макрос, настраивающий буфер для

[квадратных скобках] указаны элементы,

без знака (u), восьмеричном (о) или шест-

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

которые могут отсутствовать, жирным вы-

надцатеричном (xX) формате. Тип Х озна-

ввода-вывода.

делены элементы-модификаторы, прочие

чает, что шестнадцатеричные цифры-бук-

Аргумент stream типа FILE должен быть

символы – обязательные):

вы должны выводиться в верхнем регистре

заранее подготовлен пользователем, в от-

%[префикс][ширина][.точность][суф-

(т.е. число 0x0a1b2c3d будет выведено как

личие от аналогичной структуры, выделяе-

фикс]тип

“A1B2C3D”). Если задана точность, то пред-

мой fdevopen() динамически.

Префикс определяет общие характе-

ставление числа дополняется слева нуля-

Аргументы put и get аналогичны пере-

ристики преобразования формата. Список

ми для ее достижения.

даваемым в fdevopen().

префиксов (может быть одновременно не-

p – указатель. Аргумент трактуется, как

Аргумент rwflag – это флаги-признаки

сколько):

void * и выводится, как обычное десятич-

режима открытия потока. Может принимать

# – использовать альтернативный фор-

ное число в шестнадцатеричном формате,

одно из трех значений:

мат. Для типов c, d, i, и s игнорируется. Для

т.е. последовательность %р полностью ана-

· _FDEV_SETUP_READ – для чтения

типа o означает, что точность представле-

логична управляющей последовательности

· _FDEV_SETUP_WRITE – для записи

ния числа должна быть увеличена так, что-

%#x

· _FDEV_SETUP_RW – записи и чтения

бы первый выводимый символ был нулем.

с – символ. Аргумент трактуется как

Для типов x или X означает, что выводимое

unsigned char и выводится соответствую-

_FDEV_ERR

число будет предваряться символами “0x”

щий символ.

_FDEV_ERR – константа ошибки чтения

или “0X” соответственно.

s – строка. Аргумент трактуется как ука-

потока. Используется в функции чтения

0 – выравнивание нулями. Означает, что

затель на строку. В поток выводятся все

fdevopen().

если задана минимальная ширина пред-

символы вплоть до завершающего строку

ставления числа, то все незначащие левые

символа NULL (который не выводится).

_FDEV_EOF

символы будут заменены нулями (вместо

Если задана точность – выводится не бо-

_FDEV_EOF – константа ошибки при

пробелов). Для типов d, i, o, u, i, x, и X дан-

лее указанного количества символов, при

попытке чтения за концом потока. Исполь-

ный модификатор игнорируется.

этом наличие символа NULL в строке не

зуется в функции чтения fdevopen().

- – флаг отрицательного значения. Оз-

требуется.

начает, что выводимое значение выравни-

S – строка в сегменте кода. Аргумент

FDEV_SETUP_STREAM()

вается влево в пределах заданной шири-

трактуется как указатель на строку, разме-

FDEV_SETUP_STREAM(put, get,

ны, дополняясь справа пробелами. Если

щенную в сегменте кода (см. тип s), в отли-

rwflag) – макрос, аналогичный

применяются оба модификатора 0 и -, пос-

чие от стандартного размещения в ОЗУ.

fdev_setup_stream(), только инициализиру-

ледний имеет приоритет.

% – символ %. Никаких преобразова-

ющий переменную потока путем присвое-

“ “ (пробел) – означает, что положитель-

ний не требуется, очередной аргумент так

ния ей «возвращаемого» значения макро-

ное число должно предваряться слева про-

же не требуется – это просто вывод симво-

са. Параметры макроса аналогичны пара-

белом (т.е. резервирует место под возмож-

ла % в поток (т.е. управляющая последова-

метрам fdev_setup_stream().

ный символ минуса для отрицательных чи-

тельность %% предназначена для вывода

сел). Применяется для типов d или i.

в поток одного символа %).

fdev_close()

+ – означает, что положительные числа

eE – экспоненциальная форма записи

fdev_close() – макрос, освобождающий

всегда должны предваряться знаком плюс.

числа с плавающей точкой. Аргумент типа

любые ресурсы, связанные с открытым по-

Если использованы оба модификатора + и

double при необходимости округляется и

током. В текущей реализации он не делает

пробел, первый имеет приоритет.

выводится в формате [-]d.ddde±dd, где d –

5 7

Радиолюбитель – 11/2010

цифра. Число цифр после точки определя-

быть проигнорирован, т.е. не должен поме-

обработанных к настоящему моменту сим-

ется точностью (если не задана – принима-

щаться в элемент списка аргументов

волов потока. Никаких преобразований не

ется равной 6), если точность равна 0, то

h – означает, что аргумент в списке

выполняется. Это действие может быть про-

дробная часть не выводится и десятичная

имеет тип short int (а не int)

пущено при использовании префикса *.

точка так же не выводится. Если тип Е, то в

hh – означает, что аргумент имеет тип

[множество] – означает, что должна

экспоненциальной форме используется этот

char (а не int)

быть введена последовательность, состоя-

символ (взамен е). Показатель степени –

l – означает, что аргумент имеет тип long

щая из символов, указанных между скоб-

всегда 2 знака.

int (а не int) для целочисленного ввода или

ками []. Аргумент должен указывать на бу-

fF – простая форма записи числа с пла-

что аргумент имеет тип double для ввода

фер достаточного объема. Чтобы вместить

вающей точкой. Аргумент типа double при

чисел с плавающей точкой.

все символы, включая автоматически до-

необходимости округляется и выводится в

Размер – это десятичное число от 1 до

бавляемый NULL в конце. Множество фор-

формате [-]ddd.ddd, где d – цифра. Число

255, которое показывает, какое минималь-

мируется путем простого перечисления сим-

цифр после точки определяется точностью

ное количество символов потока должно

волов в виде строки, однако, есть особен-

(если не задана – принимается равной 6),

быть считано для интерпретации соответ-

ности:

если точность равна 0, то дробная часть

ствующего значения.

1. Если первый символ за открывающей

не выводится и десятичная точка так же

Тип – это один из следующих символов:

скобкой «^» (птичка), то остальные симво-

не выводится. Если выводится точка, то ми-

% – означает, что должен быть введен

лы образуют множество символов, исклю-

нимум одна цифра всегда выводится пе-

символ процента, преобразование не осу-

чаемых из числа вводимых.

ред ней.

ществляется

2. В множество не включается символ

gG – версия fF или eE (соответственно

d – означает, что должно быть введено

закрывающей квадратной скобки. Чтобы

с учетом регистра) с некоторыми особен-

целое (возможно, со знаком) число в деся-

все же добавить его в множество, следует

ностями. Число цифр после точки опреде-

тичном представлении, т.е. очередной ар-

поместить его сразу после открывающей

ляется точностью (если не задана – прини-

гумент в списке имеет тип int

скобкой или после «птички». В любом ином

мается равной 6), если точность равна 0, то

i – означает, что должно быть введено

случае эта скобка обозначит конец мно-

она принимается равной 1. выбор между

целое (возможно со знаком) число в деся-

жества.

вариантами fF и eE осуществляется авто-

тичном, восьмеричном или шестнадцате-

3. Чтобы добавить в множество набор

матически: форма fF используется, если

ричном формате, аргумент имеет тип int.

подряд идущих символов, следует указать

число не более 1000000, или показатель сте-

Формат числа определяется по первым сим-

первый символ, затем через дефис – пос-

пени 10 для числа меньше или равен зна-

волам: если число начинается с 0x или 0X -

ледний.

чению точности.

принимается шестнадцатеричный формат,

Примеры использования множеств:

Примечания.

если число начинается с 0 (????) – восьме-

[[0-9] – ввод последовательности, состо-

1. Ни при каких условиях не происходит

ричный, иначе принимается десятичный

ящей из символов «0», «1», «2», «3», «4»,

усечения точности результата для вывода

формат.

«5», «6», «7», «8», «9» «[«

чисел: если заданная ширина недостаточ-

o – означает, что вводится восьмерич-

[^0-9] – ввод последовательности из

на для представления числа – она игнори-

ное целое число (аргумент имеет тип

любых символов, кроме цифр

руется и выводится необходимое число

unsigned int)

[][] – ввод последовательности, состоя-

знаков.

u – означает, что вводится беззнаковое

щей из символов квадратных скобок

2. Для ширины и точности имеется ог-

целое число, аргумент имеет тип unsigned

раничение – они не могут быть более 255.

int

Функции модуля

3. Если использована не полная вер-

x – означает, что вводится число в шес-

сия функции vprintf() при сборке проекта,

тнадцатеричном представлении, аргумент

fdevopen()

а в списке аргументов присутствует чис-

имеет тип unsigned int

Определение:

ло типа double, в потоке вывода на этом

e или E, или f, или F, или g, или G – оз-

FILE * fdevopen (int(*put)(char, FILE *),

месте будет символ «?», т.е. краха не про-

начает, что вводится число в формате с

int(*get)(FILE *))

изойдет.

плавающей точкой, аргумент имеет тип float

Параметры:

4. Так как суффикс h игнорируется (по

s – означает, что вводится последова-

int(*put)(char, FILE *) – указатель на фун-

стандарту он предназначен для принуди-

тельность символов, не содержащая раз-

кцию вывода символа в поток (если имеет-

тельного приведения к типу char), эффек-

рывов, аргумент представляет собой ука-

ся намерение использовать создаваемый

тивность кода повысится, если никогда его

затель на буфер достаточной длины, что-

поток для вывода). Эта функция имеет два

не использовать в строке формата.

бы вместить всю последовательность вме-

параметра: выводимый символ и указатель

5. Суффикс l приведет к прекращению

сте с завершающим символом NULL. Ввод

на открытый поток. Эта функция должна

вывода в поток. Т.к. текущая реализация

строки прекращается, как только встретит-

возвращать 0 в случае удачного вывода, и

не поддерживает тип long long.

ся любой символ разрыва строки, например,

не ноль в случае ошибки.

6. Переменная ширина или точность не

пробел, табуляция и т.п.

int(*get)(FILE *) – указатель на функцию

реализованы, поэтому символ * в поле ши-

с – означает, что должна быть введена

для ввода символа (если имеется намере-

рины или точности приведет к прекраще-

последовательность символов, количество

ние использовать поток для ввода). Эта

нию вывода в поток.

которых определено полем размер. Аргу-

функция имеет один параметр – указатель

мент, как и для s, должен указывать на бу-

на открытый поток, и должна возвратить

Спецификация строки формата

фер достаточной длины, однако заверша-

введенный символ в случае успешного за-

для функций форматированного

ющий NULL не вводится. Вводятся все сим-

вершения. В случае попытки считать «за

ввода

волы, включая разделительные. Чтобы про-

концом данных» функция должна вернуть

Строка формата для функций ввода

пустить начальные пробелы используйте

_FDEV_EOF, в случае иных ошибок функ-

имеет строение, аналогичное строке фор-

принудительно вставленный в строку фор-

ция должна возвращать _FDEV_ERR.

мата вывода (см. Спецификация строки

мата пробел перед управляющей последо-

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

формата для функций форматированно-

вательностью.

успеха – указатель на структуру открытого

го вывода), но состоит из следующих час-

p – означает, что вводится значение

потока в динамической памяти, иначе NULL.

тей:

указателя. Ожидается, что последователь-

Описание: Эта функция заменяет

%[префикс][размер] [тип]

ность символов будет соответствовать той,

fopen(). Она позволяет открыть поток для

Префикс – это одна или более из чис-

что выводится в аналогичном случае функ-

случая, когда необходимо реализовать соб-

ла следующих последовательностей:

цией vfprintf().

ственную поддержку аппаратной части для

* – означает, что преобразование дол-

n – не вводится ничего, вместо этого в

ввода-вывода. В случае успешного завер-

жно быть выполнено, но результат должен

аргумент (типа int) заносится количество

шения функция возвращает указатель на

5 8

Радиолюбитель – 11/2010

структуру FILE, которая затем может ис-

выбираемых компоновщиком во время

vprintf()

пользоваться, как соответствующий поток

сборки проекта:

Определение:

в других функциях. Если недостаточно ди-

- обычная (по умолчанию) – реализует

int vprintf (const char *fmt, va_list ap)

намической памяти, или не определена ни

все виды преобразований, кроме предназ-

Описание: данная функция осуществ-

одна из функций put и get (т.е. попытка от-

наченных для чисел с плавающей точкой;

ляет форматированный вывод в поток

крыть поток вообще без намерения его ис-

- усеченная – реализует только базовые

stdout. Параметры и подробности см. в опи-

пользовать) – функция завершается не-

преобразования форматов целых чисел и

сании vfprintf().

удачно.

строк, кроме того, может применяться толь-

Первый поток, открытый для ввода ав-

ко префикс # (см. Спецификация строки

sprintf()

томатически ассоциируется с потоком stdin,

формата для функций форматированного

Определение:

первый поток, открытый для вывода, авто-

вывода);

int sprintf (char *s, const char *fmt,...)

матически ассоциируется с потоками stdout

- полная – реализующая полную специ-

Описание: данная функция осуществ-

и stderr.

фикацию форматов.

ляет форматированный вывод в строку s

Примечания:

Усеченная версия выбирается следую-

(область памяти для строки-результата дол-

1. Функция использует динамическое

щими параметрами компилятора:

жна иметь достаточный размер!). Подроб-

выделение памяти при помощи calloc() (и/

-Wl,-u,vfprintf -lprintf_min

ности об остальных параметрах функции и

или malloc()).

Полная версия выбирается следующи-

ее особенностях см. в описании vfprintf().

2. Для совместимости с кодом, напи-

ми параметрами компилятора:

санным для avr-libc версии 1.2 или более

-Wl,-u,vfprintf -lprintf_flt -lm

sprintf_P()

ранней,

следует

определить

Определение:

__STDIO_FDEVOPEN_COMPAT_12 до под-

vfprintf_P()

int sprintf_P (char *s, const char *fmt,...)

ключения модуля stdio.h. Это делается ис-

Определение:

Описание: данная функция осуществ-

ключительно для обеспечения совместимо-

int vfprintf_P (FILE *stream, const char *fmt,

ляет форматированный вывод в строку s

сти и упрощения миграции кода, в новых

va_list ap)

(область памяти для строки-результата дол-

проектах не используйте это!

Параметры:

жна иметь достаточный размер!), используя

FILE *stream – указатель на открытый

строку формата в сегменте кода. Подроб-

fclose()

для вывода поток

ности об остальных параметрах функции и

Определение:

const char *fmt – указатель на строку

ее особенностях см. в описании vfprintf_P().

int fclose (FILE *stream)

формата в сегменте кода

Параметры:

va_list ap – указатель на список выво-

snprintf()

FILE *stream – указатель на ранее от-

димых аргументов

Определение:

крытый поток

Возвращаемое значение: число выве-

int snprintf (char *s, size_t n, const char

Возвращаемое значение: всегда 0

денных в поток символов в случае успеш-

*fmt,...)

Описание: функция закрывает поток,

ного завершения или EOF в противном слу-

Описание: вариант функции sprintf() с

открытый функцией fdevopen() и тем самым

чае (это может быть, если поток не открыт

контролем размера строки. Параметр n оп-

делает невозможной любой ввод-вывод

для вывода).

ределяет максимальное количество симво-

через него.

Описание: это версия функции vprintf(),

лов (включая завершающий NULL), которое

Примечания: эта функция не долж-

которая использует строку формата, раз-

будет помещено в строку s. В остальном

на использоваться для потоков, открытых

мещаемую не в ОЗУ, а в сегменте кода про-

(по параметрам и поведению) полностью

с помощью fdev_setup_stream() или

граммы.

аналогична функции sprintf().

FDEV_SETUP_STREAM().

fputc()

snprintf_P()

vfprintf()

Определение:

Определение:

Определение:

int fputc (int c, FILE *stream)

int snprintf_P (char *s, size_t n, const char

int vfprintf (FILE *stream, const char *fmt,

Параметры:

*fmt,...)

va_list ap)

int c – символ для вывода

Описание: вариант функции sprintf_P()

Параметры:

FILE *stream – открытый для вывода

с контролем размера строки. Параметр n

FILE *stream – указатель на открытый

поток.

определяет максимальное количество сим-

для вывода поток

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

волов (включая завершающий NULL), кото-

const char *fmt – указатель на строку

успеха возвращает выведенный символ, в

рое будет помещено в строку s. В осталь-

формата

противном случае возвращает EOF.

ном (по параметрам и поведению) полнос-

va_list ap – указатель на список выво-

Описание: Функция выводит в поток

тью аналогична функции sprintf_P().

димых аргументов

символ (1 байт, хотя параметр имеет тип

Возвращаемое значение: число выве-

int).

vsprintf()

денных в поток символов в случае успеш-

Примечания:

Определение:

ного завершения или EOF в противном слу-

int vsprintf (char *s, const char *fmt,

чае (это может быть, если поток не открыт

printf()

va_list ap)

для вывода).

Определение:

Описание: аналог функции snprintf(),

Описание: это базовая функция фор-

int printf (const char *fmt,...)

но со списком аргументов, передаваемых

матированного файлового вывода для

Описание: данная функция осуществ-

переменной ap.

всего семейства printf-функций. Она реа-

ляет форматированный вывод в поток

лизует символьный вывод в поток stream

stderr. Параметры и подробности см. в опи-

vsprintf_P()

списка аргументов, заданного как ap в со-

сании vfprintf().

Определение:

ответствии с форматом, заданным стро-

int vsprintf_P (char *s, const char *fmt,

кой fmt (см. Спецификация строки фор-

printf_P()

va_list ap)

мата для функций форматированного

Определение:

Описание: вариант vsprintf(), но для

вывода).

int printf_P (const char *fmt,...)

строки формата в сегменте кода.

Примечания: полная реализация всех

Описание: данная функция осуществ-

возможностей форматирования требует

ляет форматированный вывод в поток

vsnprintf()

больших затрат программной памяти. С

stderr, используя строку формата в сегмен-

Определение:

целью минимизации ресурсов существует

те кода. Параметры и подробности см. в

int vsnprintf (char *s, size_t n, const char

3 варианта реализации функции vfprintf(),

описании vfprintf_P().

*fmt, va_list ap)

5 9

Радиолюбитель – 11/2010

Описание: вариант snprintf() с контро-

Описание: функция выводит в поток

указатель на строку-результат, в против-

лем количества выводимых символов, как

stdout строку str из сегмента кода, допол-

ном случае возвращает NULL.

в snprintf() и списком аргументов, переда-

няя ее символом перевода строки.

Описание: функция считывает из по-

ваемых переменной ap.

тока stream не более size-1 байтов, раз-

fwrite()

мещая их в строке-результате str. Считы-

vsnprintf_P()

Определение:

вание символов продолжается до тех пор,

Определение:

size_t fwrite (const void *ptr, size_t size,

пока не встретится символ перевода стро-

int vsnprintf_P (char *s, size_t n, const char

size_t nmemb, FILE *stream)

ки (который в результат не заносится). Если

*fmt, va_list ap)

Параметры:

не было ошибок, строка-результат завер-

Описание: вариант snprintf() с контро-

const void *ptr – указатель на первый

шается символом NULL, а функция возвра-

лем количества выводимых символов, как

выводимый элемент

щает указатель на строку-результат. В слу-

в snprintf() и списком аргументов, переда-

size_t size – размер выводимого эле-

чае ошибок возвращается NULL, и в пото-

ваемых переменной ap. Строка формата

мента

ке устанавливается признак ошибки, что-

размещается в сегменте кода.

size_t nmemb – число выводимых эле-

бы можно было использовать функцию

ментов

ferror().

fprintf()

FILE *stream – указатель на поток, от-

Определение:

крытый для записи

gets()

int fprintf (FILE *stream, const char *fmt,...)

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

Определение:

Описание: функция осуществляет фор-

успеха возвращает значение nmemb

char * gets (char *str)

матированный вывод в поток stream. См.

Описание: функция выводит в поток

Параметры:

подробности об особенностях и параметрах

stream nmemb элементов, каждый из ко-

char *str – строка-результат

в vfprintf().

торых имеет размер size байт. Указатель

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

ptr должен указывать на первый выводи-

успешного завершения возвращает указа-

fprintf_P()

мый элемент.

тель на строку-результат, в противном слу-

Определение:

чае возвращает NULL

int fprintf_P (FILE *stream, const char

fgetc()

Описание: функция действует анало-

*fmt,...)

Определение:

гично fgets(), только строка читается из по-

Описание: функция осуществляет фор-

int fgetc (FILE *stream)

тока stdin и количество считанных байт не

матированный вывод в поток stream, при-

Параметры:

контролируется.

чем строка формата размещается в сегмен-

FILE *stream – указатель на поток, от-

Примечания: отсутствие контроля

те кода. См. подробности об особенностях

крытый для чтения

количества вводимых символов налага-

и параметрах в vfprintf().

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

ет большую ответственность на програм-

символ или EOF в случае ошибки

миста.

fputs()

Описание: функция считывает символ

Определение:

(байт) из потока stream. В случае ошибки

fread()

int fputs (const char *str, FILE *stream)

или попытки чтения «за концом потока»

Определение:

Параметры:

возвращается значение EOF, поэтому

size_t fread (void *ptr, size_t size, size_t

const char *str – указатель на строку

следует использовать функции feof() и

nmemb, FILE *stream)

FILE *stream – указатель на открытый

ferror() для определения истинной причи-

Параметры:

для вывода поток

ны ошибки.

void *ptr – указатель на буфер-прием-

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

ник

ет 0 в случае успешного завершения, в про-

ungetc()

size_t size – размер каждого элемента

тивном случае возвращает EOF.

Определение:

size_t nmemb – количество элементов

Описание: Функция выводит в поток

int ungetc (int c, FILE *stream)

FILE *stream – указатель на поток. От-

stream строку str. Завершающий символ

Параметры:

крытый для чтения

NULL не выводится.

int c – символ

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

FILE *stream – указатель на поток, от-

успешного завершения возвращает значе-

fputs_P()

крытый для чтения

ние nmemb

Определение:

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

Описание: функция считывает из пото-

int fputs_P (const char *str, FILE *stream)

успеха возвращает символ с, в противном

ка stream nmemb элементов, каждый из

Описание: вариант fputs() для вывода

случае возвращает EOF.

которых имеет размер size байт и помеща-

строки из сегмента кода.

Описание: функция «заталкивает» в

ет их в буфер ptr.

поток, открытый для чтения, один символ с

Примечания: буфер должен иметь до-

puts()

(преобразуемый в unsigned char), застав-

статочный объем!

Определение:

ляя его стать следующим, считываемым при

int puts (const char *str)

вводе. Функция возвращает этот самый

clearerr()

Параметры:

символ, если не было ошибки.

Определение:

const char *str – указатель на строку

Примечания: если «заталкиваемый»

void clearerr (FILE *stream)

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

символ равен EOF, функция завершается с

Параметры:

ет 0 в случае успешного завершения, в про-

ошибкой, а поток остается неизмененным.

FILE *stream – указатель на поток

тивном случае возвращает EOF.

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

Описание: функция выводит в поток

fgets()

Описание: функция сбрасывает при-

stdout строку str, дополняя ее символом

Определение:

знаки любых ошибок потока stream.

перевода строки.

char * fgets (char *str, int size, FILE *stream)

Параметры:

feof()

puts_P()

char *str – указатель на строку-ре-

Определение:

Определение:

зультат

int feof (FILE *stream)

int puts_P (const char *str)

int size – количество вводимых байт

Параметры:

const char *str – указатель на строку

FILE *stream – указатель на поток, от-

FILE *stream – указатель на поток

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

крытый для чтения

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

ет 0 в случае успешного завершения, в про-

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

значение, если достигнут конец потока

тивном случае возвращает EOF.

успешного завершения возвращает

stream

6 0

Радиолюбитель – 11/2010