Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Formatted Output APIs

Modules

 Package convert flags
 
 Package flags
 

Macros

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

Typedefs

typedef int(* cbprintf_cb) ()
 Signature for a cbprintf callback function.
 
typedef int(* cbprintf_convert_cb) (const void *buf, size_t len, void *ctx)
 Signature for a cbprintf multibyte callback function.
 
typedef int(* cbvprintf_external_formatter_func) (cbprintf_cb out, void *ctx, const char *fmt, va_list ap)
 Signature for a external formatter function identical to cbvprintf.
 

Functions

int cbprintf_package (void *packaged, size_t len, uint32_t flags, const char *format,...)
 Capture state required to output formatted data later.
 
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.
 
int cbprintf_package_convert (void *in_packaged, size_t in_len, cbprintf_convert_cb cb, void *ctx, uint32_t flags, uint16_t *strl, size_t strl_len)
 Convert a package.
 
static int cbprintf_package_copy (void *in_packaged, size_t in_len, void *packaged, size_t len, uint32_t flags, uint16_t *strl, size_t strl_len)
 Copy package with optional appending of strings.
 
static int cbprintf_fsc_package (void *in_packaged, size_t in_len, void *packaged, size_t len)
 Convert package to fully self-contained (fsc) package.
 
int cbpprintf_external (cbprintf_cb out, cbvprintf_external_formatter_func formatter, void *ctx, void *packaged)
 Generate the output for a previously captured format operation using an external formatter.
 
int cbprintf (cbprintf_cb out, void *ctx, const char *format,...)
 *printf-like output through a callback.
 
static int cbvprintf (cbprintf_cb out, void *ctx, const char *format, va_list ap)
 varargs-aware *printf-like output through a callback.
 
static int cbvprintf_tagged_args (cbprintf_cb out, void *ctx, const char *format, va_list ap)
 varargs-aware *printf-like output through a callback with tagged arguments.
 
static int cbpprintf (cbprintf_cb out, void *ctx, void *packaged)
 Generate the output for a previously captured format operation.
 
int fprintfcb (FILE *stream, const char *format,...)
 fprintf using Zephyrs cbprintf infrastructure.
 
int vfprintfcb (FILE *stream, const char *format, va_list ap)
 vfprintf using Zephyrs cbprintf infrastructure.
 
int printfcb (const char *format,...)
 printf using Zephyrs cbprintf infrastructure.
 
int vprintfcb (const char *format, va_list ap)
 vprintf using Zephyrs cbprintf infrastructure.
 
int snprintfcb (char *str, size_t size, const char *format,...)
 snprintf using Zephyrs cbprintf infrastructure.
 
int vsnprintfcb (char *str, size_t size, const char *format, va_list ap)
 vsnprintf using Zephyrs cbprintf infrastructure.
 

Detailed Description

Macro Definition Documentation

◆ CBPRINTF_MUST_RUNTIME_PACKAGE

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

#include <zephyr/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.

Note
By default any char pointers are considered to be pointing at transient strings. This can be narrowed down to non const pointers by using CBPRINTF_PACKAGE_CONST_CHAR_RO.
Parameters
...String with arguments.
flagsoption flags. See Package flags.
Return values
1if string must be packaged in run time.
0string can be statically packaged.

◆ CBPRINTF_PACKAGE_ALIGNMENT

#define CBPRINTF_PACKAGE_ALIGNMENT

#include <zephyr/sys/cbprintf.h>

Value:
Z_POW2_CEIL(COND_CODE_1(CONFIG_CBPRINTF_PACKAGE_LONGDOUBLE, \
(sizeof(long double)), (MAX(sizeof(double), sizeof(long long)))))
#define COND_CODE_1(_flag, _if_1_code, _else_code)
Insert code depending on whether _flag expands to 1 or not.
Definition: util_macro.h:179
#define MAX(a, b)
Obtain the maximum of two values.
Definition: util.h:376

Required alignment of the buffer used for packaging.

◆ CBPRINTF_STATIC_PACKAGE

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

#include <zephyr/sys/cbprintf.h>

Value:
Z_CBPRINTF_STATIC_PACKAGE(packaged, inlen, outlen, \
align_offset, flags, __VA_ARGS__)
flags
Definition: parser.h:96

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
packagedpointer 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.
inlenset to the number of bytes available at packaged. If packaged is NULL the value is ignored.
outlenvariable 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_offsetinput 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.
flagsoption flags. See Package flags.
...formatted string with arguments. Format string must be constant.

Typedef Documentation

◆ cbprintf_cb

typedef int(* cbprintf_cb) ()

#include <zephyr/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().

◆ cbprintf_convert_cb

typedef int(* cbprintf_convert_cb) (const void *buf, size_t len, void *ctx)

#include <zephyr/sys/cbprintf.h>

Signature for a cbprintf multibyte callback function.

Parameters
bufdata.
lendata length.
ctxa pointer to an object that provides context for the operation.

return Amount of copied data or negative error code.

◆ cbvprintf_external_formatter_func

typedef int(* cbvprintf_external_formatter_func) (cbprintf_cb out, void *ctx, const char *fmt, va_list ap)

#include <zephyr/sys/cbprintf.h>

Signature for a external formatter function identical to cbvprintf.

This function expects the following parameters:

Parameters
outthe function used to emit each generated character.
ctxa pointer to an object that provides context for the external formatter.
fmta standard ISO C format string with characters and conversion specifications.
apcaptured stack arguments corresponding to the conversion specifications found within fmt.
Returns
vprintf like return values: the number of characters printed, or a negative error value returned from external formatter.

Function Documentation

◆ cbpprintf()

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

#include <zephyr/sys/cbprintf.h>

Generate the output for a previously captured format operation.

Parameters
outthe function used to emit each generated character.
ctxcontext provided when invoking out
packagedthe 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.

◆ cbpprintf_external()

int cbpprintf_external ( cbprintf_cb  out,
cbvprintf_external_formatter_func  formatter,
void *  ctx,
void *  packaged 
)

#include <zephyr/sys/cbprintf.h>

Generate the output for a previously captured format operation using an external formatter.

Parameters
outthe function used to emit each generated character.
formatterexternal formatter function.
ctxa pointer to an object that provides context for the external formatter.
packagedthe 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
printf like return values: the number of characters printed, or a negative error value returned from external formatter.

◆ cbprintf()

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

#include <zephyr/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 CONFIG_CBPRINTF_NANO is selected.
Parameters
outthe function used to emit each generated character.
ctxcontext provided when invoking out
formata 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()

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

#include <zephyr/sys/cbprintf.h>

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

Package may not be self contain since strings by default are stored by address. Package may be partially self-contained when transient (not read only) strings are appended to the package. Such package can be decoded only when there is an access to read-only strings.

Fully self-contained has (fsc) contains all strings used in the package. A package can be converted to fsc package if it was create with CBPRINTF_PACKAGE_ADD_RO_STR_POS flag. Such package will contain necessary data to find read only strings in the package and copy them into the package body.

Parameters
in_packagedpointer to original package created with CBPRINTF_PACKAGE_ADD_RO_STR_POS.
in_lenin_packaged length.
packagedpointer to location where fully self-contained version of the input package will be written. Pass a null pointer to calculate space required.
lenmust be set to the number of bytes available at packaged. Not used if packaged is null.
Return values
nonegativethe number of bytes successfully stored at packaged. This will not exceed len. If packaged is null, calculated length.
-ENOSPCif packaged was not null and the space required to store exceed len.
-EINVALif in_packaged is null.

◆ cbprintf_package()

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

#include <zephyr/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
packagedpointer 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.
lenthis 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.
flagsoption flags. See Package flags.
formata standard ISO C format string with characters and conversion specifications.
...arguments corresponding to the conversion specifications found within format.
Return values
nonegativethe number of bytes successfully stored at packaged. This will not exceed len.
-EINVALif format is not acceptable
-EFAULTif packaged alignment is not acceptable
-ENOSPCif packaged was not null and the space required to store exceed len.

◆ cbprintf_package_convert()

int cbprintf_package_convert ( void *  in_packaged,
size_t  in_len,
cbprintf_convert_cb  cb,
void *  ctx,
uint32_t  flags,
uint16_t strl,
size_t  strl_len 
)

#include <zephyr/sys/cbprintf.h>

Convert a package.

Converting may include appending strings used in the package to the package body. If input package was created with CBPRINTF_PACKAGE_ADD_RO_STR_POS or CBPRINTF_PACKAGE_ADD_RW_STR_POS, it contains information where strings are located within the package. This information can be used to copy strings during the conversion.

cb is called with portions of the output package. At the end of the conversion cb is called with null buffer.

Parameters
in_packagedInput package.
in_lenInput package length. If 0 package length will be retrieved from the in_packaged
cbcallback called with portions of the converted package. If null only length of the output package is calculated.
ctxContext provided to the cb.
flagsFlags. See Package convert flags.
[in,out]strlif packaged is null, it is a pointer to the array where strl_len first string lengths will is stored. If packaged is not null, it contains lengths of first strl_len strings. It can be used to optimize copying so that string length is calculated only once (at length calculation phase when packaged is null.)
strl_lenNumber of elements in strl array.
Return values
Positiveoutput package size.
-ENOSPCif packaged was not null and the space required to store exceed len.

◆ cbprintf_package_copy()

static int cbprintf_package_copy ( void *  in_packaged,
size_t  in_len,
void *  packaged,
size_t  len,
uint32_t  flags,
uint16_t strl,
size_t  strl_len 
)
inlinestatic

#include <zephyr/sys/cbprintf.h>

Copy package with optional appending of strings.

cbprintf_package_convert is used to convert and store converted package in the new location.

Parameters
in_packagedInput package.
in_lenInput package length. If 0 package length will be retrieved from the in_packaged
[out]packagedOutput package. If null only length of the output package is calculated.
lenAvailable space in the location pointed by packaged. Not used when packaged is null.
flagsFlags. See Package convert flags.
[in,out]strlif packaged is null, it is a pointer to the array where strl_len first string lengths will is stored. If packaged is not null, it contains lengths of first strl_len strings. It can be used to optimize copying so that string length is calculated only once (at length calculation phase when packaged is null.)
strl_lenNumber of elements in strl array.
Return values
PositiveOutput package size.
-ENOSPCif packaged was not null and the space required to store exceed len.

◆ cbvprintf()

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

#include <zephyr/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 CONFIG_CBPRINTF_LIBC_SUBSTS is selected.
The functionality of this function is significantly reduced when CONFIG_CBPRINTF_NANO is selected.
Parameters
outthe function used to emit each generated character.
ctxcontext provided when invoking out
formata standard ISO C format string with characters and conversion specifications.
apa 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 <zephyr/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
packagedpointer 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.
lenthis must be set to the number of bytes available at packaged. Ignored if packaged is NULL.
flagsoption flags. See Package flags.
formata standard ISO C format string with characters and conversion specifications.
apcaptured stack arguments corresponding to the conversion specifications found within format.
Return values
nonegativethe number of bytes successfully stored at packaged. This will not exceed len.
-EINVALif format is not acceptable
-ENOSPCif packaged was not null and the space required to store exceed len.

◆ cbvprintf_tagged_args()

static int cbvprintf_tagged_args ( cbprintf_cb  out,
void *  ctx,
const char *  format,
va_list  ap 
)
inlinestatic

#include <zephyr/sys/cbprintf.h>

varargs-aware *printf-like output through a callback with tagged arguments.

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 that the argument list ap are tagged.

Note
This function is available only when CONFIG_CBPRINTF_LIBC_SUBSTS is selected.
The functionality of this function is significantly reduced when CONFIG_CBPRINTF_NANO is selected.
Parameters
outthe function used to emit each generated character.
ctxcontext provided when invoking out
formata standard ISO C format string with characters and conversion specifications.
apa reference to the values to be converted.
Returns
the number of characters generated, or a negative error value returned from invoking out.

◆ fprintfcb()

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

#include <zephyr/sys/cbprintf.h>

fprintf using Zephyrs cbprintf infrastructure.

Note
This function is available only when CONFIG_CBPRINTF_LIBC_SUBSTS is selected.
The functionality of this function is significantly reduced when CONFIG_CBPRINTF_NANO is selected.
Parameters
streamthe stream to which the output should be written.
formata 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 <zephyr/sys/cbprintf.h>

printf using Zephyrs cbprintf infrastructure.

Note
This function is available only when CONFIG_CBPRINTF_LIBC_SUBSTS is selected.
The functionality of this function is significantly reduced when CONFIG_CBPRINTF_NANO is selected.
Parameters
formata 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 <zephyr/sys/cbprintf.h>

snprintf using Zephyrs cbprintf infrastructure.

Note
This function is available only when CONFIG_CBPRINTF_LIBC_SUBSTS is selected.
The functionality of this function is significantly reduced when CONFIG_CBPRINTF_NANO is selected.
Parameters
strwhere the formatted content should be written
sizemaximum number of chaacters for the formatted output, including the terminating null byte.
formata 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 <zephyr/sys/cbprintf.h>

vfprintf using Zephyrs cbprintf infrastructure.

Note
This function is available only when CONFIG_CBPRINTF_LIBC_SUBSTS is selected.
The functionality of this function is significantly reduced when CONFIG_CBPRINTF_NANO is selected.
Parameters
streamthe stream to which the output should be written.
formata standard ISO C format string with characters and conversion specifications.
apa reference to the values to be converted.
Returns
The number of characters printed.

◆ vprintfcb()

int vprintfcb ( const char *  format,
va_list  ap 
)

#include <zephyr/sys/cbprintf.h>

vprintf using Zephyrs cbprintf infrastructure.

Note
This function is available only when CONFIG_CBPRINTF_LIBC_SUBSTS is selected.
The functionality of this function is significantly reduced when CONFIG_CBPRINTF_NANO is selected.
Parameters
formata standard ISO C format string with characters and conversion specifications.
apa 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 <zephyr/sys/cbprintf.h>

vsnprintf using Zephyrs cbprintf infrastructure.

Note
This function is available only when CONFIG_CBPRINTF_LIBC_SUBSTS is selected.
The functionality of this function is significantly reduced when CONFIG_CBPRINTF_NANO is selected.
Parameters
strwhere the formatted content should be written
sizemaximum number of chaacters for the formatted output, including the terminating null byte.
formata standard ISO C format string with characters and conversion specifications.
apa 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.