1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
// SPDX-License-Identifier: GPL-2.0-or-later
/*
* Copyright (c) 2021 SUSE LLC
*/
#ifndef STRBUF_H_INCLUDED
#define STRBUF_H_INCLUDED
#include <errno.h>
#include <string.h>
struct strbuf {
char *buf;
size_t size;
size_t offs;
};
/**
* reset_strbuf(): prepare strbuf for new content
* @param strbuf: string buffer to reset
*
* Frees internal buffer and resets size and offset to 0.
* Can be used to cleanup a struct strbuf on stack.
*/
void reset_strbuf(struct strbuf *buf);
/**
* free_strbuf(): free resources
* @param strbuf: string buffer to discard
*
* Frees all memory occupied by a struct strbuf.
*/
void free_strbuf(struct strbuf *buf);
/**
* macro: STRBUF_INIT
*
* Use this to initialize a local struct strbuf on the stack,
* or in a global/static variable.
*/
#define STRBUF_INIT { .buf = NULL, }
/**
* macro: STRBUF_ON_STACK
*
* Define and initialize a local struct @strbuf to be cleaned up when
* the current scope is left
*/
#define STRBUF_ON_STACK(__x) \
struct strbuf __attribute__((cleanup(reset_strbuf))) (__x) = STRBUF_INIT;
/**
* new_strbuf(): allocate a struct strbuf on the heap
*
* @returns: pointer to allocated struct, or NULL in case of error.
*/
struct strbuf *new_strbuf(void);
/**
* get_strbuf_buf(): retrieve a pointer to the strbuf's buffer
* @param buf: a struct strbuf
* @returns: pointer to the string written to the strbuf so far.
*
* INTERNAL ONLY.
* DANGEROUS: Unlike the return value of get_strbuf_str(),
* this string can be written to, modifying the strbuf's content.
* USE WITH CAUTION.
* If @strbuf was never written to, the function returns NULL.
* The return value of this function must not be free()d.
*/
char *get_strbuf_buf__(struct strbuf *buf);
/**
* get_strbuf_str(): retrieve string from strbuf
* @param buf: a struct strbuf
* @returns: pointer to the string written to the strbuf so far.
*
* If @strbuf was never written to, the function returns a zero-
* length string. The return value of this function must not be
* free()d.
*/
const char *get_strbuf_str(const struct strbuf *buf);
/**
* steal_strbuf_str(): retrieve string from strbuf and reset
* @param buf: a struct strbuf
* @returns: pointer to the string written to @strbuf, or NULL
*
* After calling this function, the @strbuf is empty as if freshly
* initialized. The caller is responsible to free() the returned pointer.
* If @strbuf was never written to (not even an empty string was appended),
* the function returns NULL.
*/
char *steal_strbuf_str(struct strbuf *buf);
/**
* get_strbuf_len(): retrieve string length from strbuf
* @param buf: a struct strbuf
* @returns: the length of the string written to @strbuf so far.
*/
size_t get_strbuf_len(const struct strbuf *buf);
/**
* truncate_strbuf(): shorten the buffer
* @param buf: struct strbuf to truncate
* @param offs: new buffer position / offset
* @returns: 0 on success, negative error code otherwise.
*
* If @strbuf is freshly allocated/reset (never written to), -EFAULT
* is returned. if @offs must be higher than the current offset as returned
* by get_strbuf_len(), -ERANGE is returned. The allocated size of the @strbuf
* remains unchanged.
*/
int truncate_strbuf(struct strbuf *buf, size_t offs);
/**
* append_strbuf_str__(): append string of known length
* @param buf: the struct strbuf to write to
* @param str: the string to append, not necessarily 0-terminated
* @param slen: max number of characters to append, must be non-negative
* @returns: @slen = number of appended characters if successful (excluding
* terminating '\0'); negative error code otherwise.
*
* Notes: a 0-byte is always appended to the output buffer after @slen characters.
* 0-bytes possibly contained in the first @slen characters are copied into
* the output. If the function returns an error, @strbuf is unchanged.
*/
int append_strbuf_str__(struct strbuf *buf, const char *str, int slen);
/**
* append_strbuf_str(): append string
* @param buf: the struct strbuf to write to
* @param str: the string to append, 0-terminated
* @returns: number of appended characters if successful (excluding
* terminating '\0'); negative error code otherwise
*
* Appends the given 0-terminated string to @strbuf, expanding @strbuf's size
* as necessary. If the function returns an error, @strbuf is unchanged.
*/
int append_strbuf_str(struct strbuf *buf, const char *str);
/**
* fill_strbuf_str(): pad strbuf with a character
* @param buf: the struct strbuf to write to
* @param c: the character used for filling
* @param slen: max number of characters to append, must be non-negative
* @returns: number of appended characters if successful (excluding
* terminating '\0'); negative error code otherwise
*
* Appends the given character @slen times to @strbuf, expanding @strbuf's size
* as necessary. If the function returns an error, @strbuf is unchanged.
*/
int fill_strbuf(struct strbuf *buf, char c, int slen);
/**
* append_strbuf_quoted(): append string in double quotes, escaping quotes in string
* @param buf: the struct strbuf to write to
* @param str: the string to append, 0-terminated
* @returns: number of appended characters if successful (excluding
* terminating '\0'); negative error code otherwise
*
* Appends the given string to @strbuf, with leading and trailing double
* quotes (") added, expanding @strbuf's size as necessary. Any double quote
* characters (") in the string are transformed to a pair of double quotes ("").
* If the function returns an error, @strbuf is unchanged.
*/
int append_strbuf_quoted(struct strbuf *buf, const char *str);
/**
* print_strbuf(): print to strbuf, formatted
* @param buf: the struct strbuf to print to
* @param fmt: printf()-like format string
* @returns: number of appended characters if successful, (excluding
* terminating '\0'); negative error code otherwise
*
* Appends the arguments following @fmt, formatted as in printf(), to
* @strbuf, expanding @strbuf's size as necessary. The function makes sure that
* the output @strbuf is always 0-terminated.
* If the function returns an error, @strbuf is unchanged.
*/
__attribute__((format(printf, 2, 3)))
int print_strbuf(struct strbuf *buf, const char *fmt, ...);
#endif
|
