Nagios 4.5.4
Dev docs for Nagios core and neb-module hackers
Loading...
Searching...
No Matches
kvvec.h File Reference

Key/value vector library function and type declarations. More...

Go to the source code of this file.

Data Structures

struct  key_value
 key/value pair One of the two major components of the kvvec api More...
 
struct  kvvec_buf
 key/value vector buffer. More...
 
struct  kvvec
 key/value vector struct This is the main component of the kvvec library More...
 
#define KVVEC_INITIALIZER   { NULL, 0, 0, 0 }
 Portable initializer for stack-allocated key/value vectors.
 
#define KVVEC_FREE_KEYS   1
 Parameters for kvvec_destroy()
 
#define KVVEC_FREE_VALUES   2
 Free values when destroying a kv vector.
 
#define KVVEC_FREE_ALL   (KVVEC_FREE_KEYS | KVVEC_FREE_VALUES)
 Free both keys and values when destroying a kv vector.
 
#define KVVEC_ASSIGN   0
 Assign from buf in buf2kvvec_prealloc()
 
#define KVVEC_COPY   1
 Copy from buf in buf2kvvec_prealloc()
 
#define KVVEC_APPEND   2
 Don't reset kvvec in buf2kvvec_prealloc()
 
#define kvvec_addkv(kvv, key, value)
 Shortcut to kvvec_addkv_wlen() when lengths aren't known.
 
struct kvveckvvec_init (struct kvvec *kvv, int hint)
 Initialize a previously allocated key/value vector.
 
struct kvveckvvec_create (int hint)
 Create a key/value vector.
 
int kvvec_resize (struct kvvec *kvv, int size)
 Resize a key/value vector Used by kvvec_grow().
 
int kvvec_grow (struct kvvec *kvv, int hint)
 Grow a key/value vector.
 
unsigned int kvvec_capacity (struct kvvec *kvv)
 Return remaining storage capacity of key/value vector.
 
int kvvec_sort (struct kvvec *kvv)
 Sort a key/value vector alphabetically by key name.
 
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.
 
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 kvvec_destroy (struct kvvec *kvv, int flags)
 Destroy a key/value vector.
 
void kvvec_free_kvpairs (struct kvvec *kvv, int flags)
 Free key/value pairs associated with a key/value vector.
 
struct kvvec_bufkvvec2buf (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 kvvecbuf2kvvec (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 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.
 

Detailed Description

Key/value vector library function and type declarations.

The kvvec library is nifty as either a configuration meta-format or for IPC purposes. Take a look at the buf2kvvec() and kvvec2buf() pair of functions for the latter.

Macro Definition Documentation

◆ kvvec_addkv

#define kvvec_addkv ( kvv,
key,
value )
Value:
kvvec_addkv_wlen(kvv, key, 0, value, 0)
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.

Shortcut to kvvec_addkv_wlen() when lengths aren't known.

Parameters
kvvThe key/value vector to add this key/value pair to
keyThe key
valueThe value
Returns
0 on success, < 0 on errors

◆ KVVEC_FREE_KEYS

#define KVVEC_FREE_KEYS   1

Parameters for kvvec_destroy()

Free keys when destroying a kv vector

Function Documentation

◆ buf2kvvec()

struct kvvec * buf2kvvec ( char * str,
unsigned int len,
const char kvsep,
const char pair_sep,
int flags )
extern

Create a key/value vector from a pre-parsed buffer.

Immensely useful for ipc in combination with kvvec2buf().

Parameters
strThe buffer to convert to a key/value vector
lenLength of buffer to convert
kvsepCharacter separating key and value
pair_sepCharacter separating key/value pairs
flagsbitmask. See KVVEC_{ASSIGN,COPY,APPEND} for values
Returns
The created key/value vector

◆ buf2kvvec_prealloc()

int buf2kvvec_prealloc ( struct kvvec * kvv,
char * str,
unsigned int len,
const char kvsep,
const char pair_sep,
int flags )
extern

Parse a buffer into the pre-allocated key/value vector.

Immensely useful for ipc in combination with kvvec2buf().

Parameters
kvvA pre-allocated key/value vector to populate
strThe buffer to convert to a key/value vector
lenLength of buffer to convert
kvsepCharacter separating key and value
pair_sepCharacter separating key/value pairs
flagsbitmask. See KVVEC_{ASSIGN,COPY,APPEND} for values
Returns
The number of pairs in the created key/value vector

◆ kvvec2buf()

struct kvvec_buf * kvvec2buf ( struct kvvec * kvv,
char kv_sep,
char pair_sep,
int overalloc )
extern

Create a linear buffer of all the key/value pairs and return it as a kvvec_buf.

The caller must free() all pointers in the returned kvvec_buf (FIXME: add kvvec_buf_destroy(), or move this and its counterpart out of the kvvec api into a separate one)

Parameters
kvvThe key/value vector to convert
kv_sepCharacter separating keys and their values
pair_sepCharacter separating key/value pairs
overallocInteger determining how much extra data we should allocate. The overallocated memory is filled with nul bytes.
Returns
A pointer to a newly created kvvec_buf structure

◆ kvvec_addkv_wlen()

int kvvec_addkv_wlen ( struct kvvec * kvv,
const char * key,
int keylen,
const char * value,
int valuelen )
extern

Add a key/value pair to an existing key/value vector, with lengths of strings already calculated.

Parameters
kvvThe key/value vector to add this key/value pair to
keyThe key
keylenLength of the key
valueThe value
valuelenLength of the value
Returns
0 on success, < 0 on errors

◆ kvvec_capacity()

unsigned int kvvec_capacity ( struct kvvec * kvv)
extern

Return remaining storage capacity of key/value vector.

Parameters
[in]kvvThe key/value vector to check
Returns
Number of key/value pairs that can be stored without growing

◆ kvvec_create()

struct kvvec * kvvec_create ( int hint)
extern

Create a key/value vector.

Parameters
hintNumber of key/value pairs we expect to store
Returns
Pointer to a struct kvvec, properly initialized

◆ kvvec_destroy()

int kvvec_destroy ( struct kvvec * kvv,
int flags )
extern

Destroy a key/value vector.

Parameters
kvvThe key/value vector to destroy
flagsor'ed combination of KVVEC_FREE_{KEYS,VALUES}, or KVVEC_FREE_ALL
Returns
0 on success, < 0 on errors

◆ kvvec_foreach()

int kvvec_foreach ( struct kvvec * kvv,
void * arg,
int(* callback )(struct key_value *, void *) )
extern

Walk each key/value pair in a key/value vector, sending them as arguments to a callback function.

The callback function has no control over the iteration process and must not delete or modify the key/value vector it's operating on.

Parameters
kvvThe key/value vector to walk
argExtra argument to the callback function
callbackCallback function
Returns
0 on success, < 0 on errors

◆ kvvec_free_kvpairs()

void kvvec_free_kvpairs ( struct kvvec * kvv,
int flags )

Free key/value pairs associated with a key/value vector.

Parameters
kvvThe key/value vector to operate on
flagsflags or'ed combination of KVVEC_FREE_{KEYS,VALUES}, or KVVEC_FREE_ALL

◆ kvvec_grow()

int kvvec_grow ( struct kvvec * kvv,
int hint )
extern

Grow a key/value vector.

Used internally as needed by the kvvec api. If 'hint' is zero, the key/value capacity is increased by a third of the current capacity plus a small constant number. This uses kvvec_resize() internally.

Parameters
kvvThe key/value vector to grow
hintThe amount of key/value slots we should grow by
Returns
0 on success, < 0 on errors

◆ kvvec_init()

struct kvvec * kvvec_init ( struct kvvec * kvv,
int hint )
extern

Initialize a previously allocated key/value vector.

Parameters
kvvThe key/value vector to initialize
hintNumber of key/value pairs we expect to store
Returns
Pointer to a struct kvvec, properly initialized

◆ kvvec_resize()

int kvvec_resize ( struct kvvec * kvv,
int size )
extern

Resize a key/value vector Used by kvvec_grow().

If size is smaller than the current number of used key/value slots, -1 is returned.

Parameters
[in]kvvThe key/value vector to resize
[in]sizeThe size to grow to
Returns
0 on success, < 0 on errors

◆ kvvec_sort()

int kvvec_sort ( struct kvvec * kvv)
extern

Sort a key/value vector alphabetically by key name.

Parameters
kvvThe key/value vector to sort
Returns
0