Nios® II Software Developer Handbook

ID 683525
Date 8/28/2023
Public
Document Table of Contents

7.13.5.1. Definition of 'asnprintf()'

newlib implements a maze of 22 printf() variants, all based on the same core engine, and all with slightly different interfaces. Some are specified by the C standard, some by Posix, some are GNU extensions, and some are newlib extensions. The newlib libc web page documents the functions that conform to their respective standards.

For more information about libc, refer to the "The Red Hat newlib C Libray" web page.

The 22 variants fill a four-dimensional space of design alternatives:
  • Plain vs varargs
  • File vs buffer output
  • Output buffer management alternatives:
    • Fixed buffer, unknow length
    • Fixed buffer, known length
    • malloc()ed-and-returned buffer
    • realloc()-able buffer
  • Plain vs no-floating-point formatting support

The map to the maze is the set of prefix chars.

v*printf (mnemonic: v-for-varargs)

The canonical printf() functions take a variable number of arguments including one for each percent-specifier in the format string. This is convenient for you, but inconvenient for wrapper functions taking a variable number of arguments and then doing some sort of value-added before invoking the regular printf() library, because C provides no convenient, portable way for a function to read a variable number of arguments and then pass them to another function taking a variable number of arguments. Consequently, for each plain printf() function, the C library provides a v*printf variant which accepts the extra arguments in varargs vector format.

The "plain" (variable number of arguments) printf functions are:
  • fprintf()
  • printf()
  • asprintf()
  • asnprintf()
  • snprintf()
  • sprintf()
  • fiprintf()
  • iprintf()
  • asiprintf()
  • asniprintf()
  • sniprintf()
  • siprintf()
The fixed-number-of-argument (vararg-based) variants are:
  • vprintf()
  • vasprintf()
  • vasnprintf()
  • vsprintf()
  • vsnprintf()
  • viprintf()
  • vasiprintf()
  • vasniprintf()
  • vsiprintf()
  • vsniprintf()

*s*printf (mnemonic: prints to string buffer)

The canonical printf() function prints to an output stream; the *s*printf functions instead print into a RAM buffer, allowing the buffered results to be further processed. The functions in this family are:
  • asprintf()
  • asnprintf()
  • snprintf()
  • sprintf()
  • vasprintf()
  • vasnprintf()
  • vsprintf()
  • vsnprintf()
  • asiprintf()
  • asniprintf()
  • sniprintf()
  • siprintf()
  • vasiprintf()
  • vasniprintf()
  • vsiprintf()
  • vsniprintf()
These functions differ in part in how the destination buffer is managed:
  • The original functions in this family, like sprintf took a buffer pointer as input and wrote into it. Since the length of the buffer was not given, these functions would frequently overrun the given buffer, resulting in reliability and security issues. The functions in this family are:
    • sprintf()
    • vsprintf()
    • siprintf()
    • vsiprintf()
  • *sn*printf (mnemonic: 'n' for number of bytes in buffer): variants attempted to deal with this problem by passing a buffer length as well as a buffer, allowing the function to avoid overrunning the buffer. This mitigates the security issues but results in incorrect output when the buffer is insufficient. The functions in this family are:
    • snprintf()
    • vsnprintf()
    • sniprintf()
    • vsniprintf()
  • *as*printf (mnemonic: 'a' for aallocate): variants deal with this problem by malloc()ing and returning the buffer holding the result string. It The caller must then free() the buffer.This avoids the security and reliability issues at the cost of significant added de/allocation overhead. The functions in this family are:
    • asprintf()
    • vasprintf()
    • asiprintf()
    • vasiprintf()
  • *asn*printf: variants try to reduce this overhead by taking a buffer and a limit and realloc()ing it only if the output won't fit in the provided buffer. The functions in this family are:
    • asnprintf()
    • vasnprintf()
    • asniprintf()
    • vasniprintf()

*i*printf (mnemonic: 'i' for 'integer-only)

The usual printf() functions support formatting of floating point numbers. Consequently they not only contain a fair amount of logic to do the actual formatting of floating point numbers, but can also link into the executable image such things as a floating point emulation library. If the application does not actually use floating point numbers, and if a small RAM footprint is desired, this can be very counterproductive. Consequently, newlib defines a parallel set of printf functions which lack floating-point formatting support.

The usual set of printf() functions is:
  • fprintf()
  • vprintf()
  • printf()
  • asprintf()
  • asnprintf()
  • snprintf()
  • sprintf()
  • vasprintf()
  • vasnprintf()
  • vsprintf()
  • vsnprintf()
The parallel set of no-floating-point formatting support printf functions is:
  • fiprintf()
  • iprintf()
  • viprintf()
  • asiprintf()
  • asniprintf()
  • sniprintf()
  • siprintf()
  • vasiprintf()
  • vasniprintf()
  • vsiprintf()
  • vsniprintf()
Note: Despite the mnemonic, these functions are not really integer-only: They also support (for example) unsigned, char and string values.
Lumping all the above variants together, the full list of printf() functions supported by newlib is:
  • fprintf()
  • vprintf()
  • printf()
  • asprintf()
  • asnprintf()
  • snprintf()
  • sprintf()
  • vasprintf()
  • vasnprintf()
  • vsprintf()
  • vsnprintf()
  • fiprintf()
  • iprintf()
  • viprintf()
  • asiprintf()
  • asniprintf()
  • sniprintf()
  • siprintf()
  • vasiprintf()
  • vasniprintf()
  • vsiprintf()
  • vsniprintf()
Additional printf variants supported by newlib libc (but not libsmallc!) are:
  • dprintf, vdprintf: Print to a file descriptor (vs FILE*).
  • diprintf, vdiprintf: No-floating-point-formatting versions of above.
  • fwprintf, swprintf, vfwprintf, vswprintf, vwprintf, wprintf: Versions with wide-char support.

For more information about these printf() variants, refer to the "The Red Hat newlib C Libray" web page.