aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_buffer_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_buffer_lib.h')
-rw-r--r--src/include/gnunet_buffer_lib.h176
1 files changed, 176 insertions, 0 deletions
diff --git a/src/include/gnunet_buffer_lib.h b/src/include/gnunet_buffer_lib.h
new file mode 100644
index 000000000..c0ae06d77
--- /dev/null
+++ b/src/include/gnunet_buffer_lib.h
@@ -0,0 +1,176 @@
1/*
2 This file is part of GNUnet.
3 Copyright (C) 2020 GNUnet e.V.
4
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.
9
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.
14
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/>.
17
18 SPDX-License-Identifier: AGPL3.0-or-later
19 */
20
21/**
22 * Common buffer management functions.
23 *
24 * @author Florian Dold
25 */
26
27#ifndef GNUNET_BUFFER_LIB_H
28#define GNUNET_BUFFER_LIB_H
29
30/**
31 * Dynamically growing buffer. Can be used to construct
32 * strings and other objects with dynamic size.
33 *
34 * This structure should, in most cases, be stack-allocated and
35 * zero-initialized, like:
36 *
37 * struct GNUNET_Buffer my_buffer = { 0 };
38 */
39struct GNUNET_Buffer
40{
41 /**
42 * Capacity of the buffer.
43 */
44 size_t capacity;
45
46 /**
47 * Current write position.
48 */
49 size_t position;
50
51 /**
52 * Backing memory.
53 */
54 char *mem;
55
56 /**
57 * Log a warning if the buffer is grown over its initially allocated capacity.
58 */
59 int warn_grow;
60};
61
62
63/**
64 * Initialize a buffer with the given capacity.
65 *
66 * When a buffer is allocated with this function, a warning is logged
67 * when the buffer exceeds the initial capacity.
68 *
69 * @param buf the buffer to initialize
70 * @param capacity the capacity (in bytes) to allocate for @a buf
71 */
72void
73GNUNET_buffer_prealloc (struct GNUNET_Buffer *buf, size_t capacity);
74
75
76/**
77 * Make sure that at least @a n bytes remaining in the buffer.
78 *
79 * @param buf buffer to potentially grow
80 * @param n number of bytes that should be available to write
81 */
82void
83GNUNET_buffer_ensure_remaining (struct GNUNET_Buffer *buf, size_t n);
84
85
86/**
87 * Write bytes to the buffer.
88 *
89 * Grows the buffer if necessary.
90 *
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
94 *
95 */
96void
97GNUNET_buffer_write (struct GNUNET_Buffer *buf, const char *data, size_t len);
98
99
100/**
101 * Write a 0-terminated string to a buffer, excluding the 0-terminator.
102 *
103 * Grows the buffer if necessary.
104 *
105 * @param buf the buffer to write to
106 * @param str the string to write to @a buf
107 */
108void
109GNUNET_buffer_write_str (struct GNUNET_Buffer *buf, const char *str);
110
111
112/**
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.
116 *
117 * @param buf buffer to write to
118 * @param str string containing the new path component
119 */
120void
121GNUNET_buffer_write_path (struct GNUNET_Buffer *buf, const char *str);
122
123
124/**
125 * Write a 0-terminated formatted string to a buffer, excluding the
126 * 0-terminator.
127 *
128 * Grows the buffer if necessary.
129 *
130 * @param buf the buffer to write to
131 * @param fmt format string
132 * @param ... format arguments
133 */
134void
135GNUNET_buffer_write_fstr (struct GNUNET_Buffer *buf, const char *fmt, ...);
136
137
138/**
139 * Write a 0-terminated formatted string to a buffer, excluding the
140 * 0-terminator.
141 *
142 * Grows the buffer if necessary.
143 *
144 * @param buf the buffer to write to
145 * @param fmt format string
146 * @param args format argument list
147 */
148void
149GNUNET_buffer_write_vfstr (struct GNUNET_Buffer *buf, const char *fmt, va_list
150 args);
151
152
153/**
154 * Clear the buffer and return the string it contained.
155 * The caller is responsible to eventually #GNUNET_free
156 * the returned string.
157 *
158 * The returned string is always 0-terminated.
159 *
160 * @param buf the buffer to reap the string from
161 * @returns the buffer contained in the string
162 */
163char *
164GNUNET_buffer_reap_str (struct GNUNET_Buffer *buf);
165
166
167/**
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.
171 */
172void
173GNUNET_buffer_clear (struct GNUNET_Buffer *buf);
174
175
176#endif