NAME

       avr_stdio - <stdio.h>: Standard IO facilities

SYNOPSIS

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

Detailed Description

       #include <stdio.h>

   Introduction to the Standard IO facilities
       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
       #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 == '\n')
           uart_putchar('\r', stream);
         loop_until_bit_is_set(UCSRA, UDRE);
         UDR = c;
         return 0;
       }

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

         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 == '\n')
           uart_putchar('\r');
         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.

Function Documentation

   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 needs to be provided
       by the application. If successful, a pointer to the structure for the opened stream is
       returned. Reasons for a possible failure currently include that neither the put nor the
       get argument have been provided, thus attempting to open a stream with no IO intent at
       all, or that insufficient dynamic memory is available to establish a new stream.

       If the put function pointer is provided, the stream is opened with write intent. The
       function passed 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 could not be sent to the device.

       If the get function pointer is provided, the stream is opened with read intent. The
       function passed 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 when 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 is opened with read and write intent.

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

       fdevopen() uses calloc() (und 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 intented for providing a simple
           migration path without the need to immediately change all source code. Do not use for
           new code.

Author

       Generated automatically by Doxygen for avr-libc from the source code.