Sun, 14 Jan 2024 13:13:12 +0100
add constant for reading out printf sbo size - relates to #343
1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28 /**
29 * \file printf.h
30 * \brief Wrapper for write functions with a printf-like interface.
31 * \author Mike Becker
32 * \author Olaf Wintermann
33 * \copyright 2-Clause BSD License
34 */
36 #ifndef UCX_PRINTF_H
37 #define UCX_PRINTF_H
39 #include "common.h"
40 #include "string.h"
41 #include <stdarg.h>
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
48 /**
49 * The maximum string length that fits into stack memory.
50 */
51 extern unsigned const cx_printf_sbo_size;
53 /**
54 * A \c fprintf like function which writes the output to a stream by
55 * using a write_func.
56 *
57 * @param stream the stream the data is written to
58 * @param wfc the write function
59 * @param fmt format string
60 * @param ... additional arguments
61 * @return the total number of bytes written
62 */
63 __attribute__((__nonnull__(1, 2, 3), __format__(printf, 3, 4)))
64 int cx_fprintf(
65 void *stream,
66 cx_write_func wfc,
67 char const *fmt,
68 ...
69 );
71 /**
72 * A \c vfprintf like function which writes the output to a stream by
73 * using a write_func.
74 *
75 * @param stream the stream the data is written to
76 * @param wfc the write function
77 * @param fmt format string
78 * @param ap argument list
79 * @return the total number of bytes written
80 * @see cx_fprintf()
81 */
82 __attribute__((__nonnull__))
83 int cx_vfprintf(
84 void *stream,
85 cx_write_func wfc,
86 char const *fmt,
87 va_list ap
88 );
90 /**
91 * A \c asprintf like function which allocates space for a string
92 * the result is written to.
93 *
94 * \note The resulting string is guaranteed to be zero-terminated.
95 *
96 * @param allocator the CxAllocator used for allocating the string
97 * @param fmt format string
98 * @param ... additional arguments
99 * @return the formatted string
100 * @see cx_strfree_a()
101 */
102 __attribute__((__nonnull__(1, 2), __format__(printf, 2, 3)))
103 cxmutstr cx_asprintf_a(
104 CxAllocator const *allocator,
105 char const *fmt,
106 ...
107 );
109 /**
110 * A \c asprintf like function which allocates space for a string
111 * the result is written to.
112 *
113 * \note The resulting string is guaranteed to be zero-terminated.
114 *
115 * @param fmt format string
116 * @param ... additional arguments
117 * @return the formatted string
118 * @see cx_strfree()
119 */
120 #define cx_asprintf(fmt, ...) \
121 cx_asprintf_a(cxDefaultAllocator, fmt, __VA_ARGS__)
123 /**
124 * A \c vasprintf like function which allocates space for a string
125 * the result is written to.
126 *
127 * \note The resulting string is guaranteed to be zero-terminated.
128 *
129 * @param allocator the CxAllocator used for allocating the string
130 * @param fmt format string
131 * @param ap argument list
132 * @return the formatted string
133 * @see cx_asprintf_a()
134 */
135 __attribute__((__nonnull__))
136 cxmutstr cx_vasprintf_a(
137 CxAllocator const *allocator,
138 char const *fmt,
139 va_list ap
140 );
142 /**
143 * A \c vasprintf like function which allocates space for a string
144 * the result is written to.
145 *
146 * \note The resulting string is guaranteed to be zero-terminated.
147 *
148 * @param fmt format string
149 * @param ap argument list
150 * @return the formatted string
151 * @see cx_asprintf()
152 */
153 #define cx_vasprintf(fmt, ap) cx_vasprintf_a(cxDefaultAllocator, fmt, ap)
155 /**
156 * A \c printf like function which writes the output to a CxBuffer.
157 *
158 * @param buffer a pointer to the buffer the data is written to
159 * @param fmt the format string
160 * @param ... additional arguments
161 * @return the total number of bytes written
162 * @see ucx_fprintf()
163 */
164 #define cx_bprintf(buffer, fmt, ...) cx_fprintf((CxBuffer*)buffer, \
165 (cx_write_func) cxBufferWrite, fmt, __VA_ARGS__)
167 #ifdef __cplusplus
168 } // extern "C"
169 #endif
171 #endif //UCX_PRINTF_H