FFmpeg
bprint.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2012 Nicolas George
3  *
4  * This file is part of FFmpeg.
5  *
6  * FFmpeg is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * FFmpeg is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with FFmpeg; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19  */
20 
21 /**
22  * @file
23  * @ingroup lavu_avbprint
24  * AVBPrint public header
25  */
26 
27 #ifndef AVUTIL_BPRINT_H
28 #define AVUTIL_BPRINT_H
29 
30 #include <stdarg.h>
31 
32 #include "attributes.h"
33 #include "avstring.h"
34 
35 /**
36  * @defgroup lavu_avbprint AVBPrint
37  * @ingroup lavu_data
38  *
39  * A buffer to print data progressively
40  * @{
41  */
42 
43 /**
44  * Define a structure with extra padding to a fixed size
45  * This helps ensuring binary compatibility with future versions.
46  */
47 
48 #define FF_PAD_STRUCTURE(name, size, ...) \
49 struct ff_pad_helper_##name { __VA_ARGS__ }; \
50 typedef struct name { \
51  __VA_ARGS__ \
52  char reserved_padding[size - sizeof(struct ff_pad_helper_##name)]; \
53 } name;
54 
55 /**
56  * Buffer to print data progressively
57  *
58  * The string buffer grows as necessary and is always 0-terminated.
59  * The content of the string is never accessed, and thus is
60  * encoding-agnostic and can even hold binary data.
61  *
62  * Small buffers are kept in the structure itself, and thus require no
63  * memory allocation at all (unless the contents of the buffer is needed
64  * after the structure goes out of scope). This is almost as lightweight as
65  * declaring a local `char buf[512]`.
66  *
67  * The length of the string can go beyond the allocated size: the buffer is
68  * then truncated, but the functions still keep account of the actual total
69  * length.
70  *
71  * In other words, AVBPrint.len can be greater than AVBPrint.size and records
72  * the total length of what would have been to the buffer if there had been
73  * enough memory.
74  *
75  * Append operations do not need to be tested for failure: if a memory
76  * allocation fails, data stop being appended to the buffer, but the length
77  * is still updated. This situation can be tested with
78  * av_bprint_is_complete().
79  *
80  * The AVBPrint.size_max field determines several possible behaviours:
81  * - `size_max = -1` (= `UINT_MAX`) or any large value will let the buffer be
82  * reallocated as necessary, with an amortized linear cost.
83  * - `size_max = 0` prevents writing anything to the buffer: only the total
84  * length is computed. The write operations can then possibly be repeated in
85  * a buffer with exactly the necessary size
86  * (using `size_init = size_max = len + 1`).
87  * - `size_max = 1` is automatically replaced by the exact size available in the
88  * structure itself, thus ensuring no dynamic memory allocation. The
89  * internal buffer is large enough to hold a reasonable paragraph of text,
90  * such as the current paragraph.
91  */
92 
93 FF_PAD_STRUCTURE(AVBPrint, 1024,
94  char *str; /**< string so far */
95  unsigned len; /**< length so far */
96  unsigned size; /**< allocated memory */
97  unsigned size_max; /**< maximum allocated memory */
98  char reserved_internal_buffer[1];
99 )
100 
101 /**
102  * @name Max size special values
103  * Convenience macros for special values for av_bprint_init() size_max
104  * parameter.
105  * @{
106  */
107 
108 /**
109  * Buffer will be reallocated as necessary, with an amortized linear cost.
110  */
111 #define AV_BPRINT_SIZE_UNLIMITED ((unsigned)-1)
112 /**
113  * Use the exact size available in the AVBPrint structure itself.
114  *
115  * Thus ensuring no dynamic memory allocation. The internal buffer is large
116  * enough to hold a reasonable paragraph of text, such as the current paragraph.
117  */
118 #define AV_BPRINT_SIZE_AUTOMATIC 1
119 /**
120  * Do not write anything to the buffer, only calculate the total length.
121  *
122  * The write operations can then possibly be repeated in a buffer with
123  * exactly the necessary size (using `size_init = size_max = AVBPrint.len + 1`).
124  */
125 #define AV_BPRINT_SIZE_COUNT_ONLY 0
126 /** @} */
127 
128 /**
129  * Init a print buffer.
130  *
131  * @param buf buffer to init
132  * @param size_init initial size (including the final 0)
133  * @param size_max maximum size;
134  * - `0` means do not write anything, just count the length
135  * - `1` is replaced by the maximum value for automatic storage
136  * any large value means that the internal buffer will be
137  * reallocated as needed up to that limit
138  * - `-1` is converted to `UINT_MAX`, the largest limit possible.
139  * Check also `AV_BPRINT_SIZE_*` macros.
140  */
141 void av_bprint_init(AVBPrint *buf, unsigned size_init, unsigned size_max);
142 
143 /**
144  * Init a print buffer using a pre-existing buffer.
145  *
146  * The buffer will not be reallocated.
147  * In case size equals zero, the AVBPrint will be initialized to use
148  * the internal buffer as if using AV_BPRINT_SIZE_COUNT_ONLY with
149  * av_bprint_init().
150  *
151  * @param buf buffer structure to init
152  * @param buffer byte buffer to use for the string data
153  * @param size size of buffer
154  */
155 void av_bprint_init_for_buffer(AVBPrint *buf, char *buffer, unsigned size);
156 
157 /**
158  * Append a formatted string to a print buffer.
159  */
160 void av_bprintf(AVBPrint *buf, const char *fmt, ...) av_printf_format(2, 3);
161 
162 /**
163  * Append a formatted string to a print buffer.
164  */
165 void av_vbprintf(AVBPrint *buf, const char *fmt, va_list vl_arg);
166 
167 /**
168  * Append char c n times to a print buffer.
169  */
170 void av_bprint_chars(AVBPrint *buf, char c, unsigned n);
171 
172 /**
173  * Append data to a print buffer.
174  *
175  * @param buf bprint buffer to use
176  * @param data pointer to data
177  * @param size size of data
178  */
179 void av_bprint_append_data(AVBPrint *buf, const char *data, unsigned size);
180 
181 struct tm;
182 /**
183  * Append a formatted date and time to a print buffer.
184  *
185  * @param buf bprint buffer to use
186  * @param fmt date and time format string, see strftime()
187  * @param tm broken-down time structure to translate
188  *
189  * @note due to poor design of the standard strftime function, it may
190  * produce poor results if the format string expands to a very long text and
191  * the bprint buffer is near the limit stated by the size_max option.
192  */
193 void av_bprint_strftime(AVBPrint *buf, const char *fmt, const struct tm *tm);
194 
195 /**
196  * Allocate bytes in the buffer for external use.
197  *
198  * @param[in] buf buffer structure
199  * @param[in] size required size
200  * @param[out] mem pointer to the memory area
201  * @param[out] actual_size size of the memory area after allocation;
202  * can be larger or smaller than size
203  */
204 void av_bprint_get_buffer(AVBPrint *buf, unsigned size,
205  unsigned char **mem, unsigned *actual_size);
206 
207 /**
208  * Reset the string to "" but keep internal allocated data.
209  */
210 void av_bprint_clear(AVBPrint *buf);
211 
212 /**
213  * Test if the print buffer is complete (not truncated).
214  *
215  * It may have been truncated due to a memory allocation failure
216  * or the size_max limit (compare size and size_max if necessary).
217  */
218 static inline int av_bprint_is_complete(const AVBPrint *buf)
219 {
220  return buf->len < buf->size;
221 }
222 
223 /**
224  * Finalize a print buffer.
225  *
226  * The print buffer can no longer be used afterwards,
227  * but the len and size fields are still valid.
228  *
229  * @arg[out] ret_str if not NULL, used to return a permanent copy of the
230  * buffer contents, or NULL if memory allocation fails;
231  * if NULL, the buffer is discarded and freed
232  * @return 0 for success or error code (probably AVERROR(ENOMEM))
233  */
234 int av_bprint_finalize(AVBPrint *buf, char **ret_str);
235 
236 /**
237  * Escape the content in src and append it to dstbuf.
238  *
239  * @param dstbuf already inited destination bprint buffer
240  * @param src string containing the text to escape
241  * @param special_chars string containing the special characters which
242  * need to be escaped, can be NULL
243  * @param mode escape mode to employ, see AV_ESCAPE_MODE_* macros.
244  * Any unknown value for mode will be considered equivalent to
245  * AV_ESCAPE_MODE_BACKSLASH, but this behaviour can change without
246  * notice.
247  * @param flags flags which control how to escape, see AV_ESCAPE_FLAG_* macros
248  */
249 void av_bprint_escape(AVBPrint *dstbuf, const char *src, const char *special_chars,
250  enum AVEscapeMode mode, int flags);
251 
252 /** @} */
253 
254 #endif /* AVUTIL_BPRINT_H */
AV_BPRINT_SIZE_UNLIMITED
#define AV_BPRINT_SIZE_UNLIMITED
av_bprint_is_complete
static int av_bprint_is_complete(const AVBPrint *buf)
Test if the print buffer is complete (not truncated).
Definition: bprint.h:218
av_bprint_init
void av_bprint_init(AVBPrint *buf, unsigned size_init, unsigned size_max)
Definition: bprint.c:69
data
const char data[16]
Definition: mxf.c:149
av_bprint_init_for_buffer
void av_bprint_init_for_buffer(AVBPrint *buf, char *buffer, unsigned size)
Init a print buffer using a pre-existing buffer.
Definition: bprint.c:85
size_max
unsigned unsigned size_max
Definition: bprint.h:141
av_bprint_escape
void av_bprint_escape(AVBPrint *dstbuf, const char *src, const char *special_chars, enum AVEscapeMode mode, int flags)
Escape the content in src and append it to dstbuf.
Definition: bprint.c:268
av_printf_format
#define av_printf_format(fmtpos, attrpos)
Definition: attributes.h:161
FF_PAD_STRUCTURE
#define FF_PAD_STRUCTURE(name, size,...)
Define a structure with extra padding to a fixed size This helps ensuring binary compatibility with f...
Definition: bprint.h:48
av_bprint_strftime
void av_bprint_strftime(AVBPrint *buf, const char *fmt, const struct tm *tm)
Append a formatted date and time to a print buffer.
Definition: bprint.c:181
c
Undefined Behavior In the C some operations are like signed integer dereferencing freed accessing outside allocated Undefined Behavior must not occur in a C it is not safe even if the output of undefined operations is unused The unsafety may seem nit picking but Optimizing compilers have in fact optimized code on the assumption that no undefined Behavior occurs Optimizing code based on wrong assumptions can and has in some cases lead to effects beyond the output of computations The signed integer overflow problem in speed critical code Code which is highly optimized and works with signed integers sometimes has the problem that often the output of the computation does not c
Definition: undefined.txt:32
av_bprint_finalize
int av_bprint_finalize(AVBPrint *buf, char **ret_str)
Finalize a print buffer.
Definition: bprint.c:240
size
int size
Definition: twinvq_data.h:10344
attributes.h
size_init
unsigned size_init
Definition: bprint.h:141
av_bprintf
void av_bprintf(AVBPrint *buf, const char *fmt,...) av_printf_format(2
Append a formatted string to a print buffer.
av_bprint_get_buffer
void av_bprint_get_buffer(AVBPrint *buf, unsigned size, unsigned char **mem, unsigned *actual_size)
Allocate bytes in the buffer for external use.
Definition: bprint.c:223
len
int len
Definition: vorbis_enc_data.h:426
ret_str
static const char * ret_str(int v)
Definition: seek.c:34
buffer
the frame and frame reference mechanism is intended to as much as expensive copies of that data while still allowing the filters to produce correct results The data is stored in buffers represented by AVFrame structures Several references can point to the same frame buffer
Definition: filter_design.txt:49
av_vbprintf
void void av_vbprintf(AVBPrint *buf, const char *fmt, va_list vl_arg)
Append a formatted string to a print buffer.
Definition: bprint.c:122
mode
mode
Definition: ebur128.h:83
av_bprint_clear
void av_bprint_clear(AVBPrint *buf)
Reset the string to "" but keep internal allocated data.
Definition: bprint.c:232
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:482
av_bprint_chars
void av_bprint_chars(AVBPrint *buf, char c, unsigned n)
Append char c n times to a print buffer.
Definition: bprint.c:145
AVEscapeMode
AVEscapeMode
Definition: avstring.h:314
avstring.h
av_bprint_append_data
void av_bprint_append_data(AVBPrint *buf, const char *data, unsigned size)
Append data to a print buffer.
Definition: bprint.c:163
src
#define src
Definition: vp8dsp.c:248