Formatted Output APIs

Modules
	Package flags.

Macros
#define	CBPRINTF_PACKAGE_ALIGNMENT
	Required alignment of the buffer used for packaging. More...
#define	CBPRINTF_MUST_RUNTIME_PACKAGE(skip, ...)    Z_CBPRINTF_MUST_RUNTIME_PACKAGE(skip, __VA_ARGS__)
	Determine if string must be packaged in run time. More...
#define	CBPRINTF_STATIC_PACKAGE(packaged, inlen, outlen, align_offset, flags, ...)
	Statically package string. More...

Typedefs
typedef int(*	cbprintf_cb) ()
	Signature for a cbprintf callback function. More...

Functions
int	cbprintf_package (void *packaged, size_t len, uint32_t flags, const char *format,...)
	Capture state required to output formatted data later. More...
int	cbvprintf_package (void *packaged, size_t len, uint32_t flags, const char *format, va_list ap)
	Capture state required to output formatted data later. More...
int	cbprintf_fsc_package (void *in_packaged, size_t in_len, void *packaged, size_t len)
	Convert package to fully self-contained (fsc) package. More...
int	cbpprintf (cbprintf_cb out, void *ctx, void *packaged)
	Generate the output for a previously captured format operation. More...
int	cbprintf (cbprintf_cb out, void *ctx, const char *format,...)
	*printf-like output through a callback. More...
int	cbvprintf (cbprintf_cb out, void *ctx, const char *format, va_list ap)
	varargs-aware *printf-like output through a callback. More...
int	fprintfcb (FILE *stream, const char *format,...)
	fprintf using Zephyrs cbprintf infrastructure. More...
int	vfprintfcb (FILE *stream, const char *format, va_list ap)
	vfprintf using Zephyrs cbprintf infrastructure. More...
int	printfcb (const char *format,...)
	printf using Zephyrs cbprintf infrastructure. More...
int	vprintfcb (const char *format, va_list ap)
	vprintf using Zephyrs cbprintf infrastructure. More...
int	snprintfcb (char *str, size_t size, const char *format,...)
	snprintf using Zephyrs cbprintf infrastructure. More...
int	vsnprintfcb (char *str, size_t size, const char *format, va_list ap)
	vsnprintf using Zephyrs cbprintf infrastructure. More...

Detailed Description

Macro Definition Documentation

CBPRINTF_MUST_RUNTIME_PACKAGE

#define CBPRINTF_MUST_RUNTIME_PACKAGE	(		skip,
			...
	)		Z_CBPRINTF_MUST_RUNTIME_PACKAGE(skip, __VA_ARGS__)

#include <include/sys/cbprintf.h>

Determine if string must be packaged in run time.

Static packaging can be applied if size of the package can be determined at compile time. In general, package size can be determined at compile time if there are no string arguments which might be copied into package body if they are considered transient.

Parameters

skip	number of read only string arguments in the parameter list. It shall be non-zero if there are known read only string arguments present in the string (e.g. function name prefix in the log message).
...	String with arguments.

Return values

1	if string must be packaged in run time.
0	string can be statically packaged.

CBPRINTF_PACKAGE_ALIGNMENT

#define CBPRINTF_PACKAGE_ALIGNMENT

#include <include/sys/cbprintf.h>

Value:

        (IS_ENABLED(CONFIG_CBPRINTF_PACKAGE_LONGDOUBLE) ? \
                sizeof(long double) : MAX(sizeof(double), sizeof(long long)))

Required alignment of the buffer used for packaging.

CBPRINTF_STATIC_PACKAGE

#define CBPRINTF_STATIC_PACKAGE	(		packaged,
			inlen,
			outlen,
			align_offset,
			flags,
			...
	)

#include <include/sys/cbprintf.h>

Value:

        Z_CBPRINTF_STATIC_PACKAGE(packaged, inlen, outlen, \
                                  align_offset, flags, __VA_ARGS__)

Statically package string.

Build string package from formatted string. It assumes that formatted string is in the read only memory.

If _Generic is not supported then runtime packaging is performed.

Parameters

packaged	pointer to where the packaged data can be stored. Pass a null pointer to skip packaging but still calculate the total space required. The data stored here is relocatable, that is it can be moved to another contiguous block of memory. It must be aligned to the size of the longest argument. It is recommended to use CBPRINTF_PACKAGE_ALIGNMENT for alignment.
inlen	set to the number of bytes available at packaged. If packaged is NULL the value is ignored.
outlen	variable updated to the number of bytes required to completely store the packed information. If input buffer was too small it is set to -ENOSPC.
align_offset	input buffer alignment offset in bytes. Where offset 0 means that buffer is aligned to CBPRINTF_PACKAGE_ALIGNMENT. Xtensa requires that packaged is aligned to CBPRINTF_PACKAGE_ALIGNMENT so it must be multiply of CBPRINTF_PACKAGE_ALIGNMENT or 0.
flags	option flags. See Package flags..
...	formatted string with arguments. Format string must be constant.

Typedef Documentation

cbprintf_cb

typedef int(* cbprintf_cb) ()

#include <include/sys/cbprintf.h>

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.

Returns

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

Function Documentation

cbpprintf()

int cbpprintf	(	cbprintf_cb	out,
		void *	ctx,
		void *	packaged
	)

#include <include/sys/cbprintf.h>

Generate the output for a previously captured format operation.

Parameters

out	the function used to emit each generated character.
ctx	context provided when invoking out
packaged	the data required to generate the formatted output, as captured by cbprintf_package() or cbvprintf_package(). The alignment requirement on this data is the same as when it was initially created.

Note

Memory indicated by packaged will be modified in a non-destructive way, meaning that it could still be reused with this function again.

Returns

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

cbprintf()

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

#include <include/sys/cbprintf.h>

*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

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_NANO` 

is selected.

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.

Returns

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

cbprintf_fsc_package()

int cbprintf_fsc_package	(	void *	in_packaged,
		size_t	in_len,
		void *	packaged,
		size_t	len
	)

#include <include/sys/cbprintf.h>

Convert package to fully self-contained (fsc) package.

By default, package does not contain read only strings. However, if needed it may be converted to a fully self-contained package which contains all strings. In order to allow such conversion, original package must be created with CBPRINTF_PACKAGE_ADD_STRING_IDXS flag. Such package will contain necessary data to find read only strings in the package and copy them into package body.

Parameters

in_packaged	pointer to original package created with CBPRINTF_PACKAGE_ADD_STRING_IDXS.
in_len	in_packaged length.
packaged	pointer to location where fully self-contained version of the input package will be written. Pass a null pointer to calculate space required.
len	must be set to the number of bytes available at packaged. Not used if packaged is null.

Return values

nonegative	the number of bytes successfully stored at packaged. This will not exceed len. If packaged is null, calculated length.
-ENOSPC	if packaged was not null and the space required to store exceed len.
-EINVAL	if in_packaged is null.

cbprintf_package()

int cbprintf_package	(	void *	packaged,
		size_t	len,
		uint32_t	flags,
		const char *	format,
			...
	)

#include <include/sys/cbprintf.h>

Capture state required to output formatted data later.

Like cbprintf() but instead of processing the arguments and emitting the formatted results immediately all arguments are captured so this can be done in a different context, e.g. when the output function can block.

In addition to the values extracted from arguments this will ensure that copies are made of the necessary portions of any string parameters that are not confirmed to be stored in read-only memory (hence assumed to be safe to refer to directly later).

Parameters

packaged	pointer to where the packaged data can be stored. Pass a null pointer to store nothing but still calculate the total space required. The data stored here is relocatable, that is it can be moved to another contiguous block of memory. However, under condition that alignment is maintained. It must be aligned to at least the size of a pointer.
len	this must be set to the number of bytes available at packaged if it is not null. If packaged is null then it indicates hypothetical buffer alignment offset in bytes compared to CBPRINTF_PACKAGE_ALIGNMENT alignment. Buffer alignment offset impacts returned size of the package. Xtensa requires that buffer is always aligned to CBPRINTF_PACKAGE_ALIGNMENT so it must be multiply of CBPRINTF_PACKAGE_ALIGNMENT or 0 when packaged is null.
flags	option flags. See Package flags..
format	a standard ISO C format string with characters and conversion specifications.
...	arguments corresponding to the conversion specifications found within format.

Return values

nonegative	the number of bytes successfully stored at packaged. This will not exceed len.
-EINVAL	if format is not acceptable
-EFAULT	if packaged alignment is not acceptable
-ENOSPC	if packaged was not null and the space required to store exceed len.

cbvprintf()

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

#include <include/sys/cbprintf.h>

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

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_LIBC_SUBSTS` 

is selected.

The functionality of this function is significantly reduced when

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_NANO` 

is selected.

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.

Returns

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

cbvprintf_package()

int cbvprintf_package	(	void *	packaged,
		size_t	len,
		uint32_t	flags,
		const char *	format,
		va_list	ap
	)

#include <include/sys/cbprintf.h>

Capture state required to output formatted data later.

Like cbprintf() but instead of processing the arguments and emitting the formatted results immediately all arguments are captured so this can be done in a different context, e.g. when the output function can block.

In addition to the values extracted from arguments this will ensure that copies are made of the necessary portions of any string parameters that are not confirmed to be stored in read-only memory (hence assumed to be safe to refer to directly later).

Parameters

packaged	pointer to where the packaged data can be stored. Pass a null pointer to store nothing but still calculate the total space required. The data stored here is relocatable, that is it can be moved to another contiguous block of memory. The pointer must be aligned to a multiple of the largest element in the argument list.
len	this must be set to the number of bytes available at packaged. Ignored if packaged is NULL.
flags	option flags. See Package flags..
format	a standard ISO C format string with characters and conversion specifications.
ap	captured stack arguments corresponding to the conversion specifications found within format.

Return values

nonegative	the number of bytes successfully stored at packaged. This will not exceed len.
-EINVAL	if format is not acceptable
-ENOSPC	if packaged was not null and the space required to store exceed len.

fprintfcb()

int fprintfcb	(	FILE *	stream,
		const char *	format,
			...
	)

#include <include/sys/cbprintf.h>

fprintf using Zephyrs cbprintf infrastructure.

Note

This function is available only when

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_LIBC_SUBSTS` 

is selected.

The functionality of this function is significantly reduced when

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_NANO` 

is selected.

Parameters

stream	the stream to which the output should be written.
format	a standard ISO C format string with characters and conversion specifications.
...	arguments corresponding to the conversion specifications found within format.

return The number of characters printed.

printfcb()

int printfcb	(	const char *	format,
			...
	)

#include <include/sys/cbprintf.h>

printf using Zephyrs cbprintf infrastructure.

Note

This function is available only when

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_LIBC_SUBSTS` 

is selected.

The functionality of this function is significantly reduced when

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_NANO` 

is selected.

Parameters

format	a standard ISO C format string with characters and conversion specifications.
...	arguments corresponding to the conversion specifications found within format.

Returns

The number of characters printed.

snprintfcb()

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

#include <include/sys/cbprintf.h>

snprintf using Zephyrs cbprintf infrastructure.

Note

This function is available only when

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_LIBC_SUBSTS` 

is selected.

The functionality of this function is significantly reduced when

embed:rst:inline :kconfig:`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.

Returns

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.

vfprintfcb()

int vfprintfcb	(	FILE *	stream,
		const char *	format,
		va_list	ap
	)

#include <include/sys/cbprintf.h>

vfprintf using Zephyrs cbprintf infrastructure.

Note

This function is available only when

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_LIBC_SUBSTS` 

is selected.

The functionality of this function is significantly reduced when

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_NANO` 

is selected.

Parameters

stream	the stream to which the output should be written.
format	a standard ISO C format string with characters and conversion specifications.
ap	a reference to the values to be converted.

Returns

The number of characters printed.

vprintfcb()

int vprintfcb	(	const char *	format,
		va_list	ap
	)

#include <include/sys/cbprintf.h>

vprintf using Zephyrs cbprintf infrastructure.

Note

This function is available only when

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_LIBC_SUBSTS` 

is selected.

The functionality of this function is significantly reduced when

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_NANO` 

is selected.

Parameters

format	a standard ISO C format string with characters and conversion specifications.
ap	a reference to the values to be converted.

Returns

The number of characters printed.

vsnprintfcb()

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

#include <include/sys/cbprintf.h>

vsnprintf using Zephyrs cbprintf infrastructure.

Note

This function is available only when

embed:rst:inline :kconfig:`CONFIG_CBPRINTF_LIBC_SUBSTS` 

is selected.

The functionality of this function is significantly reduced when

embed:rst:inline :kconfig:`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.
ap	a reference to the values to be converted.

Returns

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.