Nagios
4.4.5
Dev docs for Nagios core and neb-module hackers
Main Page
Related Pages
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Macros
Pages
lib
kvvec.h
Go to the documentation of this file.
1
#ifndef LIBNAGIOS_KVVEC_H_INCLUDED
2
#define LIBNAGIOS_KVVEC_H_INCLUDED
3
4
/**
5
* @file kvvec.h
6
* @brief Key/value vector library function and type declarations
7
*
8
* The kvvec library is nifty as either a configuration meta-format
9
* or for IPC purposes. Take a look at the buf2kvvec() and kvvec2buf()
10
* pair of functions for the latter.
11
* @{
12
*/
13
14
/**
15
* key/value pair
16
* One of the two major components of the kvvec api
17
*/
18
struct
key_value
{
19
char
*
key
;
/**< The key */
20
char
*
value
;
/**< The value */
21
int
key_len
;
/**< Length of key */
22
int
value_len
;
/**< Length of value */
23
};
24
25
/**
26
* key/value vector buffer. Actually just a buffer, but one that gets
27
* used as return value and internal tracker for kvvec2buf()
28
*/
29
struct
kvvec_buf
{
30
char
*
buf
;
/**< The buffer */
31
unsigned
long
buflen
;
/**< Length of buffer */
32
unsigned
long
bufsize
;
/**< Size of buffer (includes overalloc) */
33
};
34
35
/**
36
* key/value vector struct
37
* This is the main component of the kvvec library
38
* @note This should be made opaque, with a kvvec_foreach() using a
39
* callback to iterate over key/value pairs.
40
*/
41
struct
kvvec
{
42
struct
key_value
*
kv
;
/**< The key/value array */
43
int
kv_alloc
;
/**< Allocated size of key/value array */
44
int
kv_pairs
;
/**< Number of key/value pairs */
45
int
kvv_sorted
;
/**< Determines if this kvvec has been sorted */
46
};
47
48
/** Portable initializer for stack-allocated key/value vectors */
49
#define KVVEC_INITIALIZER { NULL, 0, 0, 0 }
50
51
/** Parameters for kvvec_destroy() */
52
#define KVVEC_FREE_KEYS 1
/**< Free keys when destroying a kv vector */
53
#define KVVEC_FREE_VALUES 2
/**< Free values when destroying a kv vector */
54
/** Free both keys and values when destroying a kv vector */
55
#define KVVEC_FREE_ALL (KVVEC_FREE_KEYS | KVVEC_FREE_VALUES)
56
57
#define KVVEC_ASSIGN 0
/**< Assign from buf in buf2kvvec_prealloc() */
58
#define KVVEC_COPY 1
/**< Copy from buf in buf2kvvec_prealloc() */
59
#define KVVEC_APPEND 2
/**< Don't reset kvvec in buf2kvvec_prealloc() */
60
61
/**
62
* Initialize a previously allocated key/value vector
63
*
64
* @param kvv The key/value vector to initialize
65
* @param hint Number of key/value pairs we expect to store
66
* @return Pointer to a struct kvvec, properly initialized
67
*/
68
extern
struct
kvvec
*
kvvec_init
(
struct
kvvec
*kvv,
int
hint);
69
70
/**
71
* Create a key/value vector
72
*
73
* @param hint Number of key/value pairs we expect to store
74
* @return Pointer to a struct kvvec, properly initialized
75
*/
76
extern
struct
kvvec
*
kvvec_create
(
int
hint);
77
78
/**
79
* Resize a key/value vector
80
* Used by kvvec_grow(). If size is smaller than the current number of
81
* used key/value slots, -1 is returned.
82
*
83
* @param[in] kvv The key/value vector to resize
84
* @param[in] size The size to grow to
85
* @return 0 on success, < 0 on errors
86
*/
87
extern
int
kvvec_resize
(
struct
kvvec
*kvv,
int
size);
88
89
/**
90
* Grow a key/value vector.
91
* Used internally as needed by the kvvec api. If 'hint' is zero, the
92
* key/value capacity is increased by a third of the current capacity
93
* plus a small constant number. This uses kvvec_resize() internally.
94
*
95
* @param kvv The key/value vector to grow
96
* @param hint The amount of key/value slots we should grow by
97
* @return 0 on success, < 0 on errors
98
*/
99
extern
int
kvvec_grow
(
struct
kvvec
*kvv,
int
hint);
100
101
/**
102
* Return remaining storage capacity of key/value vector
103
* @param[in] kvv The key/value vector to check
104
* @return Number of key/value pairs that can be stored without growing
105
*/
106
extern
unsigned
int
kvvec_capacity
(
struct
kvvec
*kvv);
107
108
/**
109
* Sort a key/value vector alphabetically by key name
110
* @param kvv The key/value vector to sort
111
* @return 0
112
*/
113
extern
int
kvvec_sort
(
struct
kvvec
*kvv);
114
115
/**
116
* Add a key/value pair to an existing key/value vector, with
117
* lengths of strings already calculated
118
* @param kvv The key/value vector to add this key/value pair to
119
* @param key The key
120
* @param keylen Length of the key
121
* @param value The value
122
* @param valuelen Length of the value
123
* @return 0 on success, < 0 on errors
124
*/
125
extern
int
kvvec_addkv_wlen
(
struct
kvvec
*kvv,
const
char
*key,
int
keylen,
const
char
*value,
int
valuelen);
126
127
/**
128
* Shortcut to kvvec_addkv_wlen() when lengths aren't known
129
* @param kvv The key/value vector to add this key/value pair to
130
* @param key The key
131
* @param value The value
132
* @return 0 on success, < 0 on errors
133
*/
134
#define kvvec_addkv(kvv, key, value) kvvec_addkv_wlen(kvv, key, 0, value, 0)
135
136
/**
137
* Walk each key/value pair in a key/value vector, sending them
138
* as arguments to a callback function. The callback function has
139
* no control over the iteration process and must not delete or
140
* modify the key/value vector it's operating on.
141
* @param kvv The key/value vector to walk
142
* @param arg Extra argument to the callback function
143
* @param callback Callback function
144
* @return 0 on success, < 0 on errors
145
*/
146
extern
int
kvvec_foreach
(
struct
kvvec
*kvv,
void
*arg,
int
(*callback)(
struct
key_value
*,
void
*));
147
148
/**
149
* Destroy a key/value vector
150
* @param kvv The key/value vector to destroy
151
* @param flags or'ed combination of KVVEC_FREE_{KEYS,VALUES}, or KVVEC_FREE_ALL
152
* @return 0 on success, < 0 on errors
153
*/
154
extern
int
kvvec_destroy
(
struct
kvvec
*kvv,
int
flags);
155
156
/**
157
* Free key/value pairs associated with a key/value vector
158
* @param kvv The key/value vector to operate on
159
* @param flags flags or'ed combination of KVVEC_FREE_{KEYS,VALUES}, or KVVEC_FREE_ALL
160
*/
161
void
kvvec_free_kvpairs
(
struct
kvvec
*kvv,
int
flags);
162
163
/**
164
* Create a linear buffer of all the key/value pairs and
165
* return it as a kvvec_buf. The caller must free() all
166
* pointers in the returned kvvec_buf
167
* (FIXME: add kvvec_buf_destroy(), or move this and its counterpart
168
* out of the kvvec api into a separate one)
169
*
170
* @param kvv The key/value vector to convert
171
* @param kv_sep Character separating keys and their values
172
* @param pair_sep Character separating key/value pairs
173
* @param overalloc Integer determining how much extra data we should
174
* allocate. The overallocated memory is filled with
175
* nul bytes.
176
* @return A pointer to a newly created kvvec_buf structure
177
*/
178
extern
struct
kvvec_buf
*
kvvec2buf
(
struct
kvvec
*kvv,
char
kv_sep,
char
pair_sep,
int
overalloc);
179
180
/**
181
* Create a key/value vector from a pre-parsed buffer. Immensely
182
* useful for ipc in combination with kvvec2buf().
183
*
184
* @param str The buffer to convert to a key/value vector
185
* @param len Length of buffer to convert
186
* @param kvsep Character separating key and value
187
* @param pair_sep Character separating key/value pairs
188
* @param flags bitmask. See KVVEC_{ASSIGN,COPY,APPEND} for values
189
* @return The created key/value vector
190
*/
191
extern
struct
kvvec
*
buf2kvvec
(
char
*str,
unsigned
int
len,
const
char
kvsep,
const
char
pair_sep,
int
flags);
192
193
/**
194
* Parse a buffer into the pre-allocated key/value vector. Immensely
195
* useful for ipc in combination with kvvec2buf().
196
*
197
* @param kvv A pre-allocated key/value vector to populate
198
* @param str The buffer to convert to a key/value vector
199
* @param len Length of buffer to convert
200
* @param kvsep Character separating key and value
201
* @param pair_sep Character separating key/value pairs
202
* @param flags bitmask. See KVVEC_{ASSIGN,COPY,APPEND} for values
203
* @return The number of pairs in the created key/value vector
204
*/
205
extern
int
buf2kvvec_prealloc
(
struct
kvvec
*kvv,
char
*str,
unsigned
int
len,
const
char
kvsep,
const
char
pair_sep,
int
flags);
206
/** @} */
207
#endif
/* INCLUDE_kvvec_h__ */
Generated on Tue Oct 8 2019 00:16:59 for Nagios by
1.8.3.1