Nagios  4.3.4
Dev docs for Nagios core and neb-module hackers
Data Structures
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() More...
 
#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)   kvvec_addkv_wlen(kvv, key, 0, value, 0)
 Shortcut to kvvec_addkv_wlen() when lengths aren't known. More...
 
struct kvveckvvec_init (struct kvvec *kvv, int hint)
 Initialize a previously allocated key/value vector. More...
 
struct kvveckvvec_create (int hint)
 Create a key/value vector. More...
 
int kvvec_resize (struct kvvec *kvv, int size)
 Resize a key/value vector Used by kvvec_grow(). More...
 
int kvvec_grow (struct kvvec *kvv, int hint)
 Grow a key/value vector. More...
 
unsigned int kvvec_capacity (struct kvvec *kvv)
 Return remaining storage capacity of key/value vector. More...
 
int kvvec_sort (struct kvvec *kvv)
 Sort a key/value vector alphabetically by key name. More...
 
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. More...
 
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. More...
 
int kvvec_destroy (struct kvvec *kvv, int flags)
 Destroy a key/value vector. More...
 
void kvvec_free_kvpairs (struct kvvec *kvv, int flags)
 Free key/value pairs associated with a key/value vector. More...
 
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. More...
 
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. More...
 
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. More...
 

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 
)    kvvec_addkv_wlen(kvv, key, 0, value, 0)

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 
)

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 
)

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 
)

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 
)

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)

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)

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 
)

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(*)(struct key_value *, void *)  callback 
)

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 
)

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 
)

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 
)

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)

Sort a key/value vector alphabetically by key name.

Parameters
kvvThe key/value vector to sort
Returns
0