Nagios 4.5.4
Dev docs for Nagios core and neb-module hackers
Loading...
Searching...
No Matches
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 */
18struct 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 */
29struct 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 */
41struct 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 */
68extern 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 */
76extern 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 */
87extern 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 */
99extern 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 */
106extern 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 */
113extern 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 */
125extern 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 */
146extern 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 */
154extern 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 */
161void 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 */
178extern 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 */
191extern 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 */
205extern 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__ */
void kvvec_free_kvpairs(struct kvvec *kvv, int flags)
Free key/value pairs associated with a key/value vector.
unsigned int kvvec_capacity(struct kvvec *kvv)
Return remaining storage capacity of key/value vector.
int kvvec_addkv_wlen(struct kvvec *kvv, const char *key, int keylen, const char *value, int valuelen)
Add a key/value pair to an existing key/value vector, with lengths of strings already calculated.
struct kvvec_buf * kvvec2buf(struct kvvec *kvv, char kv_sep, char pair_sep, int overalloc)
Create a linear buffer of all the key/value pairs and return it as a kvvec_buf.
struct kvvec * kvvec_init(struct kvvec *kvv, int hint)
Initialize a previously allocated key/value vector.
int kvvec_foreach(struct kvvec *kvv, void *arg, int(*callback)(struct key_value *, void *))
Walk each key/value pair in a key/value vector, sending them as arguments to a callback function.
struct kvvec * buf2kvvec(char *str, unsigned int len, const char kvsep, const char pair_sep, int flags)
Create a key/value vector from a pre-parsed buffer.
int kvvec_resize(struct kvvec *kvv, int size)
Resize a key/value vector Used by kvvec_grow().
struct kvvec * kvvec_create(int hint)
Create a key/value vector.
int kvvec_grow(struct kvvec *kvv, int hint)
Grow a key/value vector.
int kvvec_destroy(struct kvvec *kvv, int flags)
Destroy a key/value vector.
int buf2kvvec_prealloc(struct kvvec *kvv, char *str, unsigned int len, const char kvsep, const char pair_sep, int flags)
Parse a buffer into the pre-allocated key/value vector.
int kvvec_sort(struct kvvec *kvv)
Sort a key/value vector alphabetically by key name.
key/value pair One of the two major components of the kvvec api
Definition kvvec.h:18
int value_len
Length of value.
Definition kvvec.h:22
char * key
The key.
Definition kvvec.h:19
char * value
The value.
Definition kvvec.h:20
int key_len
Length of key.
Definition kvvec.h:21
key/value vector buffer.
Definition kvvec.h:29
char * buf
The buffer.
Definition kvvec.h:30
unsigned long buflen
Length of buffer.
Definition kvvec.h:31
unsigned long bufsize
Size of buffer (includes overalloc)
Definition kvvec.h:32
key/value vector struct This is the main component of the kvvec library
Definition kvvec.h:41
int kv_alloc
Allocated size of key/value array.
Definition kvvec.h:43
struct key_value * kv
The key/value array.
Definition kvvec.h:42
int kv_pairs
Number of key/value pairs.
Definition kvvec.h:44
int kvv_sorted
Determines if this kvvec has been sorted.
Definition kvvec.h:45