Formatted Output

Applications as well as Zephyr itself requires infrastructure to format values for user consumption. The standard C99 library *printf() functionality fulfills this need for streaming output devices or memory buffers, but in an embedded system devices may not accept streamed data and memory may not be available to store the formatted output.

Internal Zephyr API traditionally provided this both for printk() and for Zephyr’s internal minimal libc, but with separate internal interfaces. Logging, tracing, shell, and other applications made use of either these APIs or standard libc routines based on build options.

The cbprintf() public APIs convert C99 format strings and arguments, providing output produced one character at a time through a callback mechanism, replacing the original internal functions and providing support for almost all C99 format specifications. Existing use of s*printf() C libraries in Zephyr can be converted to snprintfcb() to avoid pulling in libc implementations.

Several Kconfig options control the set of features that are enabled, allowing some control over features and memory usage:

CONFIG_CBPRINTF_LIBC_SUBSTS can be used to provide functions that behave like standard libc functions but use the selected cbprintf formatter rather than pulling in another formatter from libc.

In addition CONFIG_CBPRINTF_NANO can be used to revert back to the very space-optimized but limited formatter used for printk() before this capability was added.

Warning

If CONFIG_MINIMAL_LIBC is selected in combination with CONFIG_CBPRINTF_NANO formatting with C standard library functions like printf or snprintf is limited. Among other things the %n specifier, most format flags, precision control, and floating point are not supported.

API Reference

group cbprintf_apis

Typedefs

typedef int (*cbprintf_cb)()

Signature for a cbprintf callback function.

This function expects two parameters:

  • c a character to output. The output behavior should be as if this was cast to an unsigned char.

  • ctx a pointer to an object that provides context for the output operation.

The declaration does not specify the parameter types. This allows a function like fputc to be used without requiring all context pointers to be to a FILE object.

Return

the value of c cast to an unsigned char then back to int, or a negative error code that will be returned from cbprintf().

Functions

int cbprintf(cbprintf_cb out, void *ctx, const char *format, ...)

*printf-like output through a callback.

This is essentially printf() except the output is generated character-by-character using the provided out function. This allows formatting text of unbounded length without incurring the cost of a temporary buffer.

All formatting specifiers of C99 are recognized, and most are supported if the functionality is enabled.

Note

The functionality of this function is significantly reduced when CONFIG_CBPRINTF_NANO is selected.

Return

the number of characters printed, or a negative error value returned from invoking out.

Parameters

  • out: the function used to emit each generated character.

  • ctx: context provided when invoking out

  • format: a standard ISO C format string with characters and conversion specifications.

  • ...: arguments corresponding to the conversion specifications found within format.

size_t cbprintf_arglen(const char *format)

Calculate the number of words required for arguments to a cbprintf format specification.

This can be used in cases where the arguments must be copied off the stack into separate storage for processing the conversion in another context.

Note

The length returned does not count bytes. It counts native words defined as the size of an int.

Note

If CONFIG_CBPRINTF_NANO is selected the count will be incorrect if any passed arguments require more than one int.

Return

the number of int elements required to provide all arguments required for the conversion.

Parameters

  • format: a standard ISO C format string with characters and conversion specifications.

int cbvprintf(cbprintf_cb out, void *ctx, const char *format, va_list ap)

varargs-aware *printf-like output through a callback.

This is essentially vsprintf() except the output is generated character-by-character using the provided out function. This allows formatting text of unbounded length without incurring the cost of a temporary buffer.

Note

This function is available only when CONFIG_CBPRINTF_LIBC_SUBSTS is selected.

Note

The functionality of this function is significantly reduced when CONFIG_CBPRINTF_NANO is selected.

Return

the number of characters generated, or a negative error value returned from invoking out.

Parameters

  • out: the function used to emit each generated character.

  • ctx: context provided when invoking out

  • format: a standard ISO C format string with characters and conversion specifications.

  • ap: a reference to the values to be converted.

int snprintfcb(char *str, size_t size, const char *format, ...)

snprintf using Zephyrs cbprintf infrastructure.

return The number of characters that would have been written to

str, excluding the terminating null byte. This is greater than the number actually written if size is too small.
Note

The functionality of this function is significantly reduced when CONFIG_CBPRINTF_NANO is selected.

Parameters

  • str: where the formatted content should be written

  • size: maximum number of chaacters for the formatted output, including the terminating null byte.

  • format: a standard ISO C format string with characters and conversion specifications.

  • ...: arguments corresponding to the conversion specifications found within format.

int vsnprintfcb(char *str, size_t size, const char *format, va_list ap)

vsnprintf using Zephyrs cbprintf infrastructure.

return The number of characters that would have been written to

str, excluding the terminating null byte. This is greater than the number actually written if size is too small.
Note

This function is available only when CONFIG_CBPRINTF_LIBC_SUBSTS is selected.

Note

The functionality of this function is significantly reduced when CONFIG_CBPRINTF_NANO is selected.

Parameters

  • str: where the formatted content should be written

  • size: maximum number of chaacters for the formatted output, including the terminating null byte.

  • format: a standard ISO C format string with characters and conversion specifications.

  • ...: arguments corresponding to the conversion specifications found within format.

  • ap: a reference to the values to be converted.