2 This file is part of GNUnet.
3 Copyright (C) 2020 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
22 * Common buffer management functions.
24 * @author Florian Dold
27 #ifndef GNUNET_BUFFER_LIB_H
28 #define GNUNET_BUFFER_LIB_H
31 * Dynamically growing buffer. Can be used to construct
32 * strings and other objects with dynamic size.
34 * This structure should, in most cases, be stack-allocated and
35 * zero-initialized, like:
37 * struct GNUNET_Buffer my_buffer = { 0 };
42 * Capacity of the buffer.
47 * Current write position.
57 * Log a warning if the buffer is grown over its initially allocated capacity.
64 * Initialize a buffer with the given capacity.
66 * When a buffer is allocated with this function, a warning is logged
67 * when the buffer exceeds the initial capacity.
69 * @param buf the buffer to initialize
70 * @param capacity the capacity (in bytes) to allocate for @a buf
73 GNUNET_buffer_prealloc (struct GNUNET_Buffer *buf, size_t capacity);
77 * Make sure that at least @a n bytes remaining in the buffer.
79 * @param buf buffer to potentially grow
80 * @param n number of bytes that should be available to write
83 GNUNET_buffer_ensure_remaining (struct GNUNET_Buffer *buf, size_t n);
87 * Write bytes to the buffer.
89 * Grows the buffer if necessary.
91 * @param buf buffer to write to
92 * @param data data to read from
93 * @param len number of bytes to copy from @a data to @a buf
97 GNUNET_buffer_write (struct GNUNET_Buffer *buf, const char *data, size_t len);
101 * Write a 0-terminated string to a buffer, excluding the 0-terminator.
103 * Grows the buffer if necessary.
105 * @param buf the buffer to write to
106 * @param str the string to write to @a buf
109 GNUNET_buffer_write_str (struct GNUNET_Buffer *buf, const char *str);
113 * Write a path component to a buffer, ensuring that
114 * there is exactly one slash between the previous contents
115 * of the buffer and the new string.
117 * @param buf buffer to write to
118 * @param str string containing the new path component
121 GNUNET_buffer_write_path (struct GNUNET_Buffer *buf, const char *str);
125 * Write a 0-terminated formatted string to a buffer, excluding the
128 * Grows the buffer if necessary.
130 * @param buf the buffer to write to
131 * @param fmt format string
132 * @param ... format arguments
135 GNUNET_buffer_write_fstr (struct GNUNET_Buffer *buf, const char *fmt, ...);
139 * Write a 0-terminated formatted string to a buffer, excluding the
142 * Grows the buffer if necessary.
144 * @param buf the buffer to write to
145 * @param fmt format string
146 * @param args format argument list
149 GNUNET_buffer_write_vfstr (struct GNUNET_Buffer *buf, const char *fmt, va_list
154 * Clear the buffer and return the string it contained.
155 * The caller is responsible to eventually #GNUNET_free
156 * the returned string.
158 * The returned string is always 0-terminated.
160 * @param buf the buffer to reap the string from
161 * @returns the buffer contained in the string
164 GNUNET_buffer_reap_str (struct GNUNET_Buffer *buf);
168 * Free the backing memory of the given buffer.
169 * Does not free the memory of the buffer control structure,
170 * which is typically stack-allocated.
173 GNUNET_buffer_clear (struct GNUNET_Buffer *buf);