Nagios  4.4.7
Dev docs for Nagios core and neb-module hackers
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__ */
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.
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...
int value_len
Length of value.
Definition: kvvec.h:22
struct kvvec * kvvec_init(struct kvvec *kvv, int hint)
Initialize a previously allocated key/value vector.
int kv_pairs
Number of key/value pairs.
Definition: kvvec.h:44
int kvvec_grow(struct kvvec *kvv, int hint)
Grow a key/value vector.
key/value pair One of the two major components of the kvvec api
Definition: kvvec.h:18
int kvvec_sort(struct kvvec *kvv)
Sort a key/value vector alphabetically by key name.
unsigned long bufsize
Size of buffer (includes overalloc)
Definition: kvvec.h:32
key/value vector buffer.
Definition: kvvec.h:29
int kvv_sorted
Determines if this kvvec has been sorted.
Definition: kvvec.h:45
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...
void kvvec_free_kvpairs(struct kvvec *kvv, int flags)
Free key/value pairs associated with 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.
char * value
The value.
Definition: kvvec.h:20
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.
char * key
The key.
Definition: kvvec.h:19
int kv_alloc
Allocated size of key/value array.
Definition: kvvec.h:43
int kvvec_resize(struct kvvec *kvv, int size)
Resize a key/value vector Used by kvvec_grow().
int kvvec_destroy(struct kvvec *kvv, int flags)
Destroy a key/value vector.
key/value vector struct This is the main component of the kvvec library
Definition: kvvec.h:41
struct kvvec * kvvec_create(int hint)
Create a key/value vector.
unsigned int kvvec_capacity(struct kvvec *kvv)
Return remaining storage capacity of key/value vector.
struct key_value * kv
The key/value array.
Definition: kvvec.h:42
unsigned long buflen
Length of buffer.
Definition: kvvec.h:31
int key_len
Length of key.
Definition: kvvec.h:21
char * buf
The buffer.
Definition: kvvec.h:30