avr_stdio(3)

📦 version 2.2.1, in fedora 43, fedora 44, opensuse-leap 16.0

🎀 avr_stdio(3) — standard IO, but make it AVR 🎀

✨ NAME ✨

avr_stdio — that's the name, bestie. It's giving standard IO for avr-libc. 💅

✨ SYNOPSIS ✨

🧚 Macros 🧚

#define stdin   (__iob[0])
#define stdout   (__iob[1])
#define stderr   (__iob[2])
#define EOF   (-1)
#define fdev_set_udata(stream,  u)   do { (stream)->udata = u; }
    while(0)
#define fdev_get_udata(stream)   ((stream)->udata)
#define fdev_setup_stream(stream,  put,  get,  rwflag)
#define _FDEV_SETUP_READ   __SRD
#define _FDEV_SETUP_WRITE   __SWR
#define _FDEV_SETUP_RW   (__SRD|__SWR)
#define _FDEV_ERR   (-1)
#define _FDEV_EOF   (-2)
#define FDEV_SETUP_STREAM(put,  get,  rwflag)
#define fdev_close()
#define putc(__c,  __stream)   fputc(__c, __stream)
#define putchar(__c)   fputc(__c, stdout)
#define getc(__stream)   fgetc(__stream)
#define getchar()   fgetc(stdin)

🧚 Typedefs 🧚

typedef struct __file FILE

🧚 Functions 🧚

int fclose (FILE *__stream)
int vfprintf (FILE *__stream, const char *__fmt, va_list __ap)
int vfprintf_P (FILE *__stream, const char *__fmt, va_list __ap)
int fputc (int __c, FILE *__stream)
int printf (const char *__fmt,...)
int printf_P (const char *__fmt,...)
int vprintf (const char *__fmt, va_list __ap)
int sprintf (char *__s, const char *__fmt,...)
int sprintf_P (char *__s, const char *__fmt,...)
int snprintf (char *__s, size_t __n, const char *__fmt,...)
int snprintf_P (char *__s, size_t __n, const char *__fmt,...)
int vsprintf (char *__s, const char *__fmt, va_list ap)
int vsprintf_P (char *__s, const char *__fmt, va_list ap)
int vsnprintf (char *__s, size_t __n, const char *__fmt, va_list ap)
int vsnprintf_P (char *__s, size_t __n, const char *__fmt, va_list ap)
int fprintf (FILE *__stream, const char *__fmt,...)
int fprintf_P (FILE *__stream, const char *__fmt,...)
int fputs (const char *__str, FILE *__stream)
int fputs_P (const char *__str, FILE *__stream)
int puts (const char *__str)
int puts_P (const char *__str)
size_t fwrite (const void *__ptr, size_t __size, size_t __nmemb, FILE *__stream)
int fgetc (FILE *__stream)
int ungetc (int __c, FILE *__stream)
char * fgets (char *__str, int __size, FILE *__stream)
char * gets (char *__str)
size_t fread (void *__ptr, size_t __size, size_t __nmemb, FILE *__stream)
void clearerr (FILE *__stream)
int feof (FILE *__stream)
int ferror (FILE *__stream)
int vfscanf (FILE *__stream, const char *__fmt, va_list __ap)
int vfscanf_P (FILE *__stream, const char *__fmt, va_list __ap)
int fscanf (FILE *__stream, const char *__fmt,...)
int fscanf_P (FILE *__stream, const char *__fmt,...)
int scanf (const char *__fmt,...)
int scanf_P (const char *__fmt,...)
int vscanf (const char *__fmt, va_list __ap)
int sscanf (const char *__buf, const char *__fmt,...)
int sscanf_P (const char *__buf, const char *__fmt,...)
int fflush (FILE *stream)
FILE * fdevopen (int(*put)(char, FILE *), int(*get)(FILE *))

🌈 DETAILED DESCRIPTION 🌈

#include <stdio.h>

💅 Introduction to the Standard IO facilities 💅

Okay so bestie, this file declares the standard IO facilities that are implemented in avr-libc. Due to the nature of the underlying hardware, only a limited subset of standard IO is implemented. There is no actual file implementation available, so only device IO can be performed. Since there's no operating system, the application needs to provide enough details about their devices in order to make them usable by the standard IO facilities. 🦋

Due to space constraints, some functionality has not been implemented at all (like some of the printf conversions that have been left out). Nevertheless, potential users of this implementation should be warned: the printf and scanf families of functions, although usually associated with presumably simple things like the famous 'Hello, world!' program, are actually fairly complex which causes their inclusion to eat up a fair amount of code space. Also, they are not fast due to the nature of interpreting the format string at run-time. Whenever possible, resorting to the (sometimes non-standard) predetermined conversion facilities that are offered by avr-libc will usually cost much less in terms of speed and code size. 💅

💅 Tunable options for code size vs. feature set 💅

In order to allow programmers a code size vs. functionality tradeoff, the function vfprintf() which is the heart of the printf family can be selected in different flavours using linker options. See the documentation of vfprintf() for a detailed description. The same applies to vfscanf() and the scanf family of functions. 🔥

💅 Outline of the chosen API 💅

The standard streams stdin, stdout, and stderr are provided, but contrary to the C standard, since avr-libc has no knowledge about applicable devices, these streams are not already pre-initialized at application startup. Also, since there is no notion of 'file' whatsoever to avr-libc, there is no function fopen() that could be used to associate a stream to some device. (See note 1.) Instead, the function fdevopen() is provided to associate a stream to a device, where the device needs to provide a function to send a character, to receive a character, or both. There is no differentiation between 'text' and 'binary' streams inside avr-libc. Character \n is sent literally down to the device's put() function. If the device requires a carriage return (\r) character to be sent before the linefeed, its put() routine must implement this (see note 2). ✨

As an alternative method to fdevopen(), the macro fdev_setup_stream() might be used to setup a user-supplied FILE structure. 🎀

It should be noted that the automatic conversion of a newline character into a carriage return - newline sequence breaks binary transfers. If binary transfers are desired, no automatic conversion should be performed, but instead any string that aims to issue a CR-LF sequence must use '\r\n' explicitly. 💀

For convenience, the first call to fdevopen() that opens a stream for reading will cause the resulting stream to be aliased to stdin. Likewise, the first call to fdevopen() that opens a stream for writing will cause the resulting stream to be aliased to both, stdout, and stderr. Thus, if the open was done with both, read and write intent, all three standard streams will be identical. Note that these aliases are indistinguishable from each other, thus calling fclose() on such a stream will also effectively close all of its aliases (note 3). 👑

It is possible to tie additional user data to a stream, using fdev_set_udata(). The backend put and get functions can then extract this user data using fdev_get_udata(), and act appropriately. For example, a single put function could be used to talk to two different UARTs that way, or the put and get functions could keep internal state between calls there. 🌈

💅 Format strings in flash ROM 💅

All the printf and scanf family functions come in two flavours: the standard name, where the format string is expected to be in SRAM, as well as a version with the suffix _P where the format string is expected to reside in the flash ROM. The macro PSTR (explained in <avr/pgmspace.h>: Program Space Utilities) becomes very handy for declaring these format strings. ⭐

💅 Running stdio without malloc() 💅

By default, fdevopen() requires malloc(). As this is often not desired in the limited environment of a microcontroller, an alternative option is provided to run completely without malloc(). 🧚

The macro fdev_setup_stream() is provided to prepare a user-supplied FILE buffer for operation with stdio. 💜

💅 Example 💅

Check out this example, bestie:

       #include <stdio.h>

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

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

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

         if (c == '0)    ', stream);
           uart_putchar('
         loop_until_bit_is_set(UCSRA, UDRE);
         UDR = c;
         return 0;
       }

       int
       main(void)
       {
         init_uart();
         stdout = &mystdout;
         printf("Hello, world!0);

         return 0;
       }

This example uses the initializer form FDEV_SETUP_STREAM() rather than the function-like fdev_setup_stream(), so all data initialization happens during C start-up. ✨

If streams initialized that way are no longer needed, they can be destroyed by first calling the macro fdev_close(), and then destroying the object itself. No call to fclose() should be issued for these streams. While calling fclose() itself is harmless, it will cause an undefined reference to free() and thus cause the linker to link the malloc module into the application. 🫶

💅 Notes 💅

Note 1:

It might have been possible to implement a device abstraction that is compatible with fopen() but since this would have required to parse a string, and to take all the information needed either out of this string, or out of an additional table that would need to be provided by the application, this approach was not taken. 💅

Note 2:

This basically follows the Unix approach: if a device such as a terminal needs special handling, it is in the domain of the terminal device driver to provide this functionality. Thus, a simple function suitable as put() for fdevopen() that talks to a UART interface might look like this: 🎀

       int
       uart_putchar(char c, FILE *stream)
       {

         if (c == '0)    ', stream);
           uart_putchar('
         loop_until_bit_is_set(UCSRA, UDRE);
         UDR = c;
         return 0;
       }

Note 3:

This implementation has been chosen because the cost of maintaining an alias is considerably smaller than the cost of maintaining full copies of each stream. Yet, providing an implementation that offers the complete set of standard streams was deemed to be useful. Not only that writing printf() instead of fprintf(mystream, ...) saves typing work, but since avr-gcc needs to resort to pass all arguments of variadic functions on the stack (as opposed to passing them in registers for functions that take a fixed number of parameters), the ability to pass one parameter less by implying stdin or stdout will also save some execution time. 🔥

✨ Macro Definition Documentation ✨

💖 #define _FDEV_EOF (-2)

The return code for when a device read hits an end-of-file sitch. 🫶

You'd use this in the get function of fdevopen().

💖 #define _FDEV_ERR (-1)

The return code for when a device read hits an error sitch. 😭

You'd use this in the get function of fdevopen().

💖 #define _FDEV_SETUP_READ __SRD

fdev_setup_stream() with read intent, bestie.

💖 #define _FDEV_SETUP_RW (__SRD|__SWR)

fdev_setup_stream() with read/write intent. Both vibes at once, no cap.

💖 #define _FDEV_SETUP_WRITE __SWR

fdev_setup_stream() with write intent.

💖 #define EOF (-1)

EOF declares the value that gets returned by a whole bunch of standard IO functions when something goes wrong. And listen — since the AVR platform (as of rn) doesn't have an abstraction for actual files, its whole "end of file" origin story is lowkey meaningless here. It's just the error value, periodt.

💖 #define fdev_close()

This macro frees up any library resources that might be associated with stream. You should call it when stream isn't needed anymore, right before your app is about to destroy the stream object itself. ✨

(Currently, this macro evaluates to nothing, but that might change in future versions of the library. So like, call it anyway, bestie. Future you says thanks. 💅)

💖 #define fdev_get_udata(stream) ((stream)->udata)

This macro retrieves a pointer to user defined data from a FILE stream object. Grab your stuff back, girl. 🎀

💖 #define fdev_set_udata(stream, u) do { (stream)->udata = u; } while(0)

This macro inserts a pointer to user defined data into a FILE stream object.

The user data is super useful for tracking state in the put and get functions you hand over to fdevopen(). iykyk 💅

💖 #define fdev_setup_stream(stream, put, get, rwflag)

Okay so this sets up a user-supplied buffer as an stdio stream. What it does: it takes a user-supplied buffer stream, and sets it up as a stream that's valid for stdio operations — basically like one you'd have gotten dynamically from fdevopen(). The buffer you're setting up must be of type FILE. 🦋

The arguments put and get are identical to the ones you'd need to pass to fdevopen().

The rwflag argument can take one of the values _FDEV_SETUP_READ, _FDEV_SETUP_WRITE, or _FDEV_SETUP_RW — for read, write, or read/write intent, respectively.

Note: No assignments to the standard streams will be performed by fdev_setup_stream(). If you wanna use standard streams, the user has to assign them. Also see the section under Running stdio without malloc(). 👑

💖 #define FDEV_SETUP_STREAM(put, get, rwflag)

Initializer for a user-supplied stdio stream. This macro acts similar to fdev_setup_stream(), except it's meant to be used as the initializer of a variable of type FILE. 🌸

The remaining arguments are used exactly as explained in fdev_setup_stream().

💖 #define getc(__stream) fgetc(__stream)

The macro getc used to be a "fast" macro implementation doing the exact same thing as fgetc(). But for space constraints, in avr-libc it's literally just an alias for fgetc. Glow-down, not glow-up. 💀

💖 #define getchar(void) fgetc(stdin)

The macro getchar reads a character from stdin. Return values and error handling are identical to fgetc(). 💜

💖 #define putc(__c, __stream) fputc(__c, __stream)

The macro putc used to be a "fast" macro implementation doing the exact same thing as fputc(). But again, space constraints — in avr-libc it's just an alias for fputc. 🙈

💖 #define putchar(__c) fputc(__c, stdout)

The macro putchar sends character c to stdout. ✨

💖 #define stderr (__iob[2])

Stream destined for error output. Unless you specifically assign it otherwise, it's identical to stdout. 😭

If stderr should point to another stream, you must explicitly assign it the result of another fdevopen() — without closing the previous stderr (since that would also close stdout). Do not do that, bestie. That's a no. 🙅

💖 #define stdin (__iob[0])

Stream that's gonna be used as an input stream by the simplified functions that don't take a stream argument.

The first stream opened with read intent using fdevopen() gets assigned to stdin. 💅

💖 #define stdout (__iob[1])

Stream that's gonna be used as an output stream by the simplified functions that don't take a stream argument.

The first stream opened with write intent using fdevopen() gets assigned to both, stdin, and stderr. (Yes, both. That's what it says. 👑)

🌈 Typedef Documentation 🌈

🦋 typedef struct __file FILE

FILE is the opaque structure that gets passed around between the various standard IO functions. Mysterious. Iconic. We don't look inside. 💅

🔥 Function Documentation 🔥

⭐ void clearerr (FILE * __stream)

Clear the error and end-of-file flags of stream. Reset the vibe. ✨

⭐ int fclose (FILE * __stream)

This function closes stream, and disallows any further IO to and from it. Bye girl. 👋

When you're using fdevopen() to set up the stream, you need to call fclose() in order to free the internal resources that got allocated.

If the stream was set up using fdev_setup_stream() or FDEV_SETUP_STREAM(), use fdev_close() instead. (Different girl, different function. 🎀)

It currently always returns 0 (for success).

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

This function is a replacement for fopen().

It opens a stream for a device where the actual device implementation has to be provided by the application. If it succeeds, you get a pointer to the structure for the opened stream. Reasons it might fail currently include: neither the put nor the get argument was provided (so you're trying to open a stream with no IO intent at all, girl what), or there isn't enough dynamic memory available to establish a new stream. 💀

If the put function pointer is provided, the stream opens with write intent. The function you pass as put shall take two arguments — the first a character to write to the device, and the second a pointer to FILE — and shall return 0 if the output was successful, and a nonzero value if the character couldn't be sent to the device.

If the get function pointer is provided, the stream opens with read intent. The function you pass as get shall take a pointer to FILE as its single argument, and return one character from the device, passed as an int type. If an error occurs while trying to read from the device, it shall return _FDEV_ERR. If an end-of-file condition was reached while reading from the device, _FDEV_EOF shall be returned.

If both functions are provided, the stream opens with read and write intent. Main character energy. 👑

The first stream opened with read intent gets assigned to stdin, and the first one opened with write intent gets assigned to both, stdout and stderr.

fdevopen() uses calloc() (and thus malloc()) in order to allocate the storage for the new stream.

Note: If the macro __STDIO_FDEVOPEN_COMPAT_12 is declared before including <stdio.h>, a function prototype for fdevopen() will be chosen that is backwards compatible with avr-libc version 1.2 and before. This is solely intended for providing a simple migration path without needing to immediately change all your source code. Do not use for new code. Fr fr, don't. 🚫

⭐ int feof (FILE * __stream)

Test the end-of-file flag of stream. Heads up: this flag can only be cleared by a call to clearerr(). 💅

⭐ int ferror (FILE * __stream)

Test the error flag of stream. Same deal — this flag can only be cleared by a call to clearerr().

⭐ int fflush (FILE * stream)

Flush stream.

This is a null operation provided for source-code compatibility only, since the standard IO implementation currently doesn't perform any buffering. It's giving "we have flushing at home". 🫶

⭐ int fgetc (FILE * __stream)

The function fgetc reads a character from stream. It returns the character, or EOF in case end-of-file was encountered or an error occurred. You must use feof() or ferror() to tell those two situations apart. Don't guess, bestie. 😭

⭐ char* fgets (char * __str, int __size, FILE * __stream)

Read at most size - 1 bytes from stream, until a newline character was encountered, and store the characters in the buffer pointed to by str. Unless an error was encountered while reading, the string will then be terminated with a NUL character.

If an error was encountered, the function returns NULL and sets the error flag of stream, which you can test using ferror(). Otherwise, a pointer to the string gets returned. ✨

⭐ int fprintf (FILE * __stream, const char * __fmt, ...)

The function fprintf performs formatted output to stream. See vfprintf() for details.

⭐ int fprintf_P (FILE * __stream, const char * __fmt, ...)

Variant of fprintf() that uses a fmt string residing in program memory. 🧚

⭐ int fputc (int __c, FILE * __stream)

The function fputc sends the character c (though it's given as type int) to stream. It returns the character, or EOF in case an error occurred.

⭐ int fputs (const char * __str, FILE * __stream)

Write the string pointed to by str to stream stream.

Returns 0 on success and EOF on error.

⭐ int fputs_P (const char * __str, FILE * __stream)

Variant of fputs() where str resides in program memory. 💖

⭐ size_t fread (void * __ptr, size_t __size, size_t __nmemb, FILE * __stream)

Read nmemb objects, size bytes each, from stream, to the buffer pointed to by ptr.

Returns the number of objects successfully read — i.e. nmemb — unless an input error occured or end-of-file was encountered. You must use feof() and ferror() to tell those two conditions apart. 👑

⭐ int fscanf (FILE * __stream, const char * __fmt, ...)

The function fscanf performs formatted input, reading the input data from stream.

See vfscanf() for details.

⭐ int fscanf_P (FILE * __stream, const char * __fmt, ...)

Variant of fscanf() using a fmt string in program memory. 🎀

⭐ size_t fwrite (const void * __ptr, size_t __size, size_t __nmemb, FILE * __stream)

Write nmemb objects, size bytes each, to stream. The first byte of the first object is referenced by ptr.

Returns the number of objects successfully written — i.e. nmemb — unless an output error occured.

⭐ char* gets (char * __str)

Similar to fgets(), except it operates on stream stdin, and the trailing newline (if any) will not be stored in the string. It's the caller's responsibility to provide enough storage to hold the characters read. So like, be careful, bestie. 🙈

⭐ int printf (const char * __fmt, ...)

The function printf performs formatted output to stream stdout. See vfprintf() for details. ✨

⭐ int printf_P (const char * __fmt, ...)

Variant of printf() that uses a fmt string residing in program memory.

⭐ int puts (const char * __str)

Write the string pointed to by str, and a trailing newline character, to stdout. 🌸

⭐ int puts_P (const char * __str)

Variant of puts() where str resides in program memory.

⭐ int scanf (const char * __fmt, ...)

The function scanf performs formatted input from stream stdin.

See vfscanf() for details.

⭐ int scanf_P (const char * __fmt, ...)

Variant of scanf() where fmt resides in program memory. 💜

⭐ int snprintf (char * __s, size_t __n, const char * __fmt, ...)

Like sprintf(), but instead of assuming s to be of infinite size, no more than n characters (including the trailing NUL character) will be converted to s.

Returns the number of characters that would have been written to s if there were enough space. (So it tells you the truth even when it can't fit it all. Honest queen. 👑)

snprintf_P()

int snprintf_P (char * __s, size_t __n, const char * __fmt,  ...)

It's the snprintf() vibe, but the fmt string is living its best life in program memory 🧠✨

sprintf()

int sprintf (char * __s, const char * __fmt,  ...)

Basically printf(), except the formatted characters get yeeted into the string s instead of a stream 🎀

sprintf_P()

int sprintf_P (char * __s, const char * __fmt,  ...)

Same energy as sprintf(), but once again the fmt string is chilling in program memory 💾💅

sscanf()

int sscanf (const char * __buf, const char * __fmt,  ...)

So sscanf does formatted input, and it reads that input data straight out of the buffer that buf is pointing at 📥 (like, it's the reading-from-a-string girlie)

Want the deets? Go look at vfscanf() — that's where the tea is ☕

sscanf_P()

int sscanf_P (const char * __buf, const char * __fmt,  ...)

sscanf() again, but the fmt string is a program-memory girlie 🌈

ungetc()

int ungetc (int __c, FILE * __stream)

okay so ungetc() takes the character c (converted to an unsigned char) and pushes it back onto the input stream that stream points at 🔄💫 And the pushed-back character? Yeah, the next read on that stream is gonna hand it right back to you. Iconic behavior, no notes.

Currently, only a single character can be pushed back onto the stream. That's the limit bestie, don't get greedy 🙈

Return value tea: ungetc() returns the character that got pushed back after the conversion, or EOF if the whole operation fails 😭 And heads up — if the value of the argument c character equals EOF, the operation will fail and the stream stays exactly how it was. No changes, periodt. 💀

vfprintf()

int vfprintf (FILE * __stream, const char * __fmt, va_list __ap)

vfprintf is literally the central facility of the whole printf family 👑 Like, the main character. It outputs values to stream under the control of a format string that gets passed in fmt, and the actual values to print come in as a variable argument list, ap ✨

Returns: the number of characters written to stream, or EOF if there's an error. And rn, that error basically only happens if stream wasn't opened with write intent 🚫✍️

🌸 The Format String, explained by me, your bestie 🌸

The format string is made up of zero or more directives:

  • Ordinary characters (anything that is not %) — these get copied to the output stream unchanged, no drama 💖
  • Conversion specifications — each one fetches zero or more subsequent arguments. Every conversion specification starts with the % character. And the arguments must properly correspond (after type promotion, okay?!) with the conversion specifier 👀

After the %, here's what shows up, in this exact sequence:

  1. Zero or more of these flags:
    • # — the value gets converted to an "alternate form". For c, d, i, s, and u conversions, this option does nothing, sorry. For o conversions, the precision of the number gets increased to force the first character of the output string to be a zero (except when a zero value is printed with an explicit precision of zero). For x and X conversions, a non-zero result gets the string 0x (or 0X for X conversions) prepended to it ✨
    • 0 (zero) — Zero padding. For all conversions, the converted value gets padded on the left with zeros instead of blanks. But if a precision is given with a numeric conversion (d, i, o, u, i, x, and X), the 0 flag is ignored 🚫
    • - — a negative field width flag; the converted value gets left-adjusted on the field boundary. So it's padded on the right with blanks, instead of on the left with blanks or zeros. And a - overrides a 0 if you give both, so pick a lane bestie 💅
    • + — a sign must always be placed before a number produced by a signed conversion. A + overrides a space if both are used 👑
  2. An optional decimal digit string specifying a minimum field width 📏 If the converted value has fewer characters than the field width, it gets padded with spaces on the left (or right, if the left-adjustment flag has been given) to fill out that field width.
  3. An optional precision, written as a period . followed by an optional digit string. If the digit string is omitted, the precision is taken as zero. This gives the minimum number of digits to appear for d, i, o, u, x, and X conversions, or the maximum number of characters to be printed from a string for s conversions 🌟
  4. An optional l or h length modifier, which specifies that the argument for the d, i, o, u, x, or X conversion is a long int rather than int. The h is ignored, since short int is equivalent to int 🤷‍♀️
  5. A character that specifies the type of conversion to be applied.

💖 The conversion specifiers and what they mean 💖

  • diouxX — the int (or appropriate variant) argument gets converted to signed decimal (d and i), unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal (x and X) notation. The letters abcdef are used for x conversions; the letters ABCDEF are used for X conversions. The precision, if there is one, gives the minimum number of digits that must appear; if the converted value needs fewer digits, it gets padded on the left with zeros 🧮
  • p — the void * argument is taken as an unsigned integer, and converted similarly to how a %#x command would do it 🎯
  • c — the int argument gets converted to an unsigned char, and the resulting character is written ✍️
  • s — the char * argument is expected to be a pointer to an array of character type (aka a pointer to a string). Characters from the array are written up to (but not including) a terminating NUL character; if a precision is specified, no more than the number specified get written. If a precision is given, no null character needs to be present; but if the precision isn't specified, or is greater than the size of the array, the array must contain a terminating NUL character 🚨
  • % — a % gets written. No argument is converted. The complete conversion specification is %% 💜
  • eE — the double argument gets rounded and converted into the format [-]d.ddde±dd, where there's one digit before the decimal-point character and the number of digits after it equals the precision. If the precision is missing, it's taken as 6; if the precision is zero, no decimal-point character appears. An E conversion uses the letter E (rather than e) to introduce the exponent. The exponent always contains two digits; if the value is zero, the exponent is 00 🔬
  • fF — the double argument gets rounded and converted to decimal notation in the format [-]ddd.ddd, where the number of digits after the decimal-point character equals the precision specification. If the precision is missing, it's taken as 6; if the precision is explicitly zero, no decimal-point character appears. If a decimal point appears, at least one digit appears before it 🍓
  • gG — the double argument gets converted in style f or e (or F or E for G conversions). The precision specifies the number of significant digits. If the precision is missing, 6 digits are given; if the precision is zero, it's treated as 1. Style e is used if the exponent from its conversion is less than -4 or greater than or equal to the precision. Trailing zeros get removed from the fractional part of the result; a decimal point appears only if it's followed by at least one digit ✂️
  • S — just like the s format, except the pointer is expected to point to a program-memory (ROM) string instead of a RAM string 🧚
In no case does a non-existent or small field width cause truncation of a numeric field — if the result of a conversion is wider than the field width, the field gets expanded to contain the conversion result. The math will not be silenced 💪

🦋 The three flavours of vfprintf() 🦋

Since the full implementation of all the features above becomes fairly large, you can pick between three different flavours of vfprintf() using linker options 🔗

  • The default vfprintf() implements all the mentioned functionality except floating point conversions.
  • There's a minimized version of vfprintf() that only implements the very basic integer and string conversion facilities — and only the # additional option can be specified using conversion flags (those flags are parsed correctly from the format specification, but then simply ignored). You ask for this version with these compiler options:
-Wl,-u,vfprintf -lprintf_min
  • And if you need the full functionality including the floating point conversions, these are the options you want:
-Wl,-u,vfprintf -lprintf_flt -lm

⚠️ Limitations ⚠️

  • The specified width and precision can be at most 255. That's the ceiling bestie, don't test it 🙈

📝 Notes 📝

notes time, and oop — there's more coming, so stay with me 💜

okay so continuing from where we left off, bestie 💖 — here are the vfprintf() caveats you need to know:

  • for floating-point conversions, if you link the default or minimized version of vfprintf(), the symbol ? will be output and the double argument will be skipped. so your output below will not be crashed. For the default version, the width field and the 'pad to left' ( symbol minus ) option will work in this case. 💅
  • the hh length modifier is ignored (the char argument is promoted to int). more exactly, this realization does not check the number of h symbols. 🙈
  • but the ll length modifier will abort the output, because this realization does not operate long long arguments. 💀
  • the variable width or precision field (an asterisk * symbol) is not realized and will abort the output. 😭
lowkey important: those aborts are real, so watch your format strings, bestie.
  • int vfprintf_P (FILE * __stream, const char * __fmt, va_list __ap) — it's giving vfprintf() but the fmt string lives in program memory. ✨
  • int vfscanf (FILE * stream, const char * fmt, va_list ap) — formatted input, bestie. This function is literally the heart of the scanf family of functions. 💖

Characters are read from stream and processed in a way described by fmt. Conversion results will be assigned to the parameters passed via ap. The format string fmt is scanned for conversion specifications. Anything that doesn't comprise a conversion specification is taken as text that is matched literally against the input. White space in the format string will match any white space in the data (including none), all other characters match only itself. Processing is aborted as soon as the data and format string no longer match, or there is an error or end-of-file condition on stream.

Most conversions skip leading white space before starting the actual conversion.

Conversions are introduced with the character %. Possible options can follow the %:

  • a * indicating that the conversion should be performed but the conversion result is to be discarded; no parameters will be processed from ap,
  • the character h indicating that the argument is a pointer to short int (rather than int),
  • the 2 characters hh indicating that the argument is a pointer to char (rather than int).
  • the character l indicating that the argument is a pointer to long int (rather than int, for integer type conversions), or a pointer to float (for floating point conversions),

In addition, a maximal field width may be specified as a nonzero positive decimal integer, which will restrict the conversion to at most this many characters from the input stream. This field width is limited to at most 255 characters which is also the default value (except for the c conversion that defaults to 1).

The following conversion flags are supported:

  • % — Matches a literal % character. This is not a conversion.
  • d — Matches an optionally signed decimal integer; the next pointer must be a pointer to int.
  • i — Matches an optionally signed integer; the next pointer must be a pointer to int. The integer is read in base 16 if it begins with 0x or 0X, in base 8 if it begins with 0, and in base 10 otherwise. Only characters that correspond to the base are used.
  • o — Matches an octal integer; the next pointer must be a pointer to unsigned int.
  • u — Matches an optionally signed decimal integer; the next pointer must be a pointer to unsigned int.
  • x — Matches an optionally signed hexadecimal integer; the next pointer must be a pointer to unsigned int.
  • f — Matches an optionally signed floating-point number; the next pointer must be a pointer to float.
  • e, g, F, E, G — Equivalent to f.
  • s — Matches a sequence of non-white-space characters; the next pointer must be a pointer to char, and the array must be large enough to accept all the sequence and the terminating NUL character. The input string stops at white space or at the maximum field width, whichever occurs first.
  • c — Matches a sequence of width count characters (default 1); the next pointer must be a pointer to char, and there must be enough room for all the characters (no terminating NUL is added). The usual skip of leading white space is suppressed. To skip white space first, use an explicit space in the format.
  • [ — Matches a nonempty sequence of characters from the specified set of accepted characters; the next pointer must be a pointer to char, and there must be enough room for all the characters in the string, plus a terminating NUL character. The usual skip of leading white space is suppressed. The string is to be made up of characters in (or not in) a particular set; the set is defined by the characters between the open bracket [ character and a close bracket ] character. The set excludes those characters if the first character after the open bracket is a circumflex ^. To include a close bracket in the set, make it the first character after the open bracket or the circumflex; any other position will end the set. The hyphen character - is also special; when placed between two other characters, it adds all intervening characters to the set. To include a hyphen, make it the last character before the final close bracket. For instance, [^]0-9-] means the set of everything except close bracket, zero through nine, and hyphen. The string ends with the appearance of a character not in the (or, with a circumflex, in) set or when the field width runs out. Note that usage of this conversion enlarges the stack expense.
  • p — Matches a pointer value (as printed by p in printf()); the next pointer must be a pointer to void.
  • n — Nothing is expected; instead, the number of characters consumed thus far from the input is stored through the next pointer, which must be a pointer to int. This is not a conversion, although it can be suppressed with the * flag.

These functions return the number of input items assigned, which can be fewer than provided for, or even zero, in the event of a matching failure. Zero indicates that, while there was input available, no conversions were assigned; typically this is due to an invalid input character, such as an alphabetic character for a d conversion. The value EOF is returned if an input failure occurs before any conversion such as an end-of-file occurs. If an error or end-of-file occurs after conversion has begun, the number of conversions which were successfully completed is returned.

By default, all the conversions described above are available except the floating-point conversions and the width is limited to 255 characters. The float-point conversion will be available in the extended version provided by the library libscanf_flt.a. Also in this case the width is not limited (exactly, it is limited to 65535 characters). To link a program against the extended version, use the following compiler flags in the link stage:

-Wl,-u,vfscanf -lscanf_flt -lm

A third version is available for environments that are tight on space. In addition to the restrictions of the standard one, this version implements no %[ specification. This version is provided in the library libscanf_min.a, and can be requested using the following options in the link stage:

-Wl,-u,vfscanf -lscanf_min -lm
  • int vfscanf_P (FILE * __stream, const char * __fmt, va_list __ap) — variant of vfscanf() using a fmt string in program memory. 🧚
  • int vprintf (const char * __fmt, va_list __ap) — performs formatted output to stream stdout, taking a variable argument list as in vfprintf(). See vfprintf() for details. ✨
  • int vscanf (const char * __fmt, va_list __ap) — performs formatted input from stream stdin, taking a variable argument list as in vfscanf(). See vfscanf() for details. 💖
  • int vsnprintf (char * __s, size_t __n, const char * __fmt, va_list ap) — like vsprintf(), but instead of assuming s to be of infinite size, no more than n characters (including the trailing NUL character) will be converted to s. Returns the number of characters that would have been written to s if there were enough space. 🎀
  • int vsnprintf_P (char * __s, size_t __n, const char * __fmt, va_list ap) — variant of vsnprintf() that uses a fmt string that resides in program memory. 🌸
  • int vsprintf (char * __s, const char * __fmt, va_list ap) — like sprintf() but takes a variable argument list for the arguments. 💅
  • int vsprintf_P (char * __s, const char * __fmt, va_list ap) — variant of vsprintf() that uses a fmt string that resides in program memory. 🦋

👑 Author 👑

Generated automatically by Doxygen for avr-libc from the source code. (yes bestie, that's the whole author section 💅)

Version 2.1.0 — dated Sat Jan 29 2022 — from the avr_stdio(3) manual page. bye bestie, go slay some embedded C! 💖✨👑

📦 where this page comes from