96cf9949f7
Use the @option directive to ensure the generated documentation links to the specified Kconfig option. Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
242 lines
7.5 KiB
C
242 lines
7.5 KiB
C
/*
|
|
* Copyright (c) 2020 Nordic Semiconductor ASA
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
#ifndef ZEPHYR_INCLUDE_SYS_CBPRINTF_H_
|
|
#define ZEPHYR_INCLUDE_SYS_CBPRINTF_H_
|
|
|
|
#include <stdarg.h>
|
|
#include <stddef.h>
|
|
#include <toolchain.h>
|
|
|
|
#ifdef CONFIG_CBPRINTF_LIBC_SUBSTS
|
|
#include <stdio.h>
|
|
#endif /* CONFIG_CBPRINTF_LIBC_SUBSTS */
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @defgroup cbprintf_apis Formatted Output APIs
|
|
* @ingroup support_apis
|
|
* @{
|
|
*/
|
|
|
|
/** @brief Signature for a cbprintf callback function.
|
|
*
|
|
* This function expects two parameters:
|
|
*
|
|
* * @p c a character to output. The output behavior should be as if
|
|
* this was cast to an unsigned char.
|
|
* * @p 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 @c fputc to be used without requiring all context pointers to
|
|
* be to a @c FILE object.
|
|
*
|
|
* @return the value of @p c cast to an unsigned char then back to
|
|
* int, or a negative error code that will be returned from
|
|
* cbprintf().
|
|
*/
|
|
typedef int (*cbprintf_cb)(/* int c, void *ctx */);
|
|
|
|
/** @brief *printf-like output through a callback.
|
|
*
|
|
* This is essentially printf() except the output is generated
|
|
* character-by-character using the provided @p 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 @option{CONFIG_CBPRINTF_NANO} is selected.
|
|
*
|
|
* @param out the function used to emit each generated character.
|
|
*
|
|
* @param ctx context provided when invoking out
|
|
*
|
|
* @param format a standard ISO C format string with characters and conversion
|
|
* specifications.
|
|
*
|
|
* @param ... arguments corresponding to the conversion specifications found
|
|
* within @p format.
|
|
*
|
|
* @return the number of characters printed, or a negative error value
|
|
* returned from invoking @p out.
|
|
*/
|
|
__printf_like(3, 4)
|
|
int cbprintf(cbprintf_cb out, void *ctx, const char *format, ...);
|
|
|
|
/** @brief varargs-aware *printf-like output through a callback.
|
|
*
|
|
* This is essentially vsprintf() except the output is generated
|
|
* character-by-character using the provided @p out function. This allows
|
|
* formatting text of unbounded length without incurring the cost of a
|
|
* temporary buffer.
|
|
*
|
|
* @note This function is available only when
|
|
* @option{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
|
|
*
|
|
* @note The functionality of this function is significantly reduced when
|
|
* @option{CONFIG_CBPRINTF_NANO} is selected.
|
|
*
|
|
* @param out the function used to emit each generated character.
|
|
*
|
|
* @param ctx context provided when invoking out
|
|
*
|
|
* @param format a standard ISO C format string with characters and conversion
|
|
* specifications.
|
|
*
|
|
* @param ap a reference to the values to be converted.
|
|
*
|
|
* @return the number of characters generated, or a negative error value
|
|
* returned from invoking @p out.
|
|
*/
|
|
int cbvprintf(cbprintf_cb out, void *ctx, const char *format, va_list ap);
|
|
|
|
#ifdef CONFIG_CBPRINTF_LIBC_SUBSTS
|
|
|
|
/** @brief fprintf using Zephyrs cbprintf infrastructure.
|
|
*
|
|
* @note This function is available only when
|
|
* @option{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
|
|
*
|
|
* @note The functionality of this function is significantly reduced
|
|
* when @option{CONFIG_CBPRINTF_NANO} is selected.
|
|
*
|
|
* @param stream the stream to which the output should be written.
|
|
*
|
|
* @param format a standard ISO C format string with characters and
|
|
* conversion specifications.
|
|
*
|
|
* @param ... arguments corresponding to the conversion specifications found
|
|
* within @p format.
|
|
*
|
|
* return The number of characters printed.
|
|
*/
|
|
__printf_like(2, 3)
|
|
int fprintfcb(FILE * stream, const char *format, ...);
|
|
|
|
/** @brief vfprintf using Zephyrs cbprintf infrastructure.
|
|
*
|
|
* @note This function is available only when
|
|
* @option{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
|
|
*
|
|
* @note The functionality of this function is significantly reduced when
|
|
* @option{CONFIG_CBPRINTF_NANO} is selected.
|
|
*
|
|
* @param stream the stream to which the output should be written.
|
|
*
|
|
* @param format a standard ISO C format string with characters and conversion
|
|
* specifications.
|
|
*
|
|
* @param ap a reference to the values to be converted.
|
|
*
|
|
* @return The number of characters printed.
|
|
*/
|
|
int vfprintfcb(FILE *stream, const char *format, va_list ap);
|
|
|
|
/** @brief printf using Zephyrs cbprintf infrastructure.
|
|
*
|
|
* @note This function is available only when
|
|
* @option{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
|
|
*
|
|
* @note The functionality of this function is significantly reduced
|
|
* when @option{CONFIG_CBPRINTF_NANO} is selected.
|
|
*
|
|
* @param format a standard ISO C format string with characters and
|
|
* conversion specifications.
|
|
*
|
|
* @param ... arguments corresponding to the conversion specifications found
|
|
* within @p format.
|
|
*
|
|
* @return The number of characters printed.
|
|
*/
|
|
__printf_like(1, 2)
|
|
int printfcb(const char *format, ...);
|
|
|
|
/** @brief vprintf using Zephyrs cbprintf infrastructure.
|
|
*
|
|
* @note This function is available only when
|
|
* @option{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
|
|
*
|
|
* @note The functionality of this function is significantly reduced when
|
|
* @option{CONFIG_CBPRINTF_NANO} is selected.
|
|
*
|
|
* @param format a standard ISO C format string with characters and conversion
|
|
* specifications.
|
|
*
|
|
* @param ap a reference to the values to be converted.
|
|
*
|
|
* @return The number of characters printed.
|
|
*/
|
|
int vprintfcb(const char *format, va_list ap);
|
|
|
|
/** @brief snprintf using Zephyrs cbprintf infrastructure.
|
|
*
|
|
* @note This function is available only when
|
|
* @option{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
|
|
*
|
|
* @note The functionality of this function is significantly reduced
|
|
* when @option{CONFIG_CBPRINTF_NANO} is selected.
|
|
*
|
|
* @param str where the formatted content should be written
|
|
*
|
|
* @param size maximum number of chaacters for the formatted output,
|
|
* including the terminating null byte.
|
|
*
|
|
* @param format a standard ISO C format string with characters and
|
|
* conversion specifications.
|
|
*
|
|
* @param ... arguments corresponding to the conversion specifications found
|
|
* within @p format.
|
|
*
|
|
* @return The number of characters that would have been written to @p
|
|
* str, excluding the terminating null byte. This is greater than the
|
|
* number actually written if @p size is too small.
|
|
*/
|
|
__printf_like(3, 4)
|
|
int snprintfcb(char *str, size_t size, const char *format, ...);
|
|
|
|
/** @brief vsnprintf using Zephyrs cbprintf infrastructure.
|
|
*
|
|
* @note This function is available only when
|
|
* @option{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
|
|
*
|
|
* @note The functionality of this function is significantly reduced when
|
|
* @option{CONFIG_CBPRINTF_NANO} is selected.
|
|
*
|
|
* @param str where the formatted content should be written
|
|
*
|
|
* @param size maximum number of chaacters for the formatted output, including
|
|
* the terminating null byte.
|
|
*
|
|
* @param format a standard ISO C format string with characters and conversion
|
|
* specifications.
|
|
*
|
|
* @param ap a reference to the values to be converted.
|
|
*
|
|
* @return The number of characters that would have been written to @p
|
|
* str, excluding the terminating null byte. This is greater than the
|
|
* number actually written if @p size is too small.
|
|
*/
|
|
int vsnprintfcb(char *str, size_t size, const char *format, va_list ap);
|
|
|
|
#endif /* CONFIG_CBPRINTF_LIBC_SUBSTS */
|
|
|
|
/**
|
|
* @}
|
|
*/
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* ZEPHYR_INCLUDE_SYS_CBPRINTF_H_ */
|