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


Define Documentation

#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:
kvv The key/value vector to add this key/value pair to
key The key
value The value
Returns:
0 on success, < 0 on errors
#define KVVEC_FREE_KEYS   1

Parameters for kvvec_destroy().

Free keys when destroying a kv vector


Function Documentation

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

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

Immensely useful for ipc in combination with kvvec2buf().

Parameters:
str The buffer to convert to a key/value vector
len Length of buffer to convert
kvsep Character separating key and value
pair_sep Character separating key/value pairs
flags bitmask. See KVVEC_{ASSIGN,COPY,APPEND} for values
Returns:
The created 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.

Immensely useful for ipc in combination with kvvec2buf().

Parameters:
kvv A pre-allocated key/value vector to populate
str The buffer to convert to a key/value vector
len Length of buffer to convert
kvsep Character separating key and value
pair_sep Character separating key/value pairs
flags bitmask. See KVVEC_{ASSIGN,COPY,APPEND} for values
Returns:
The number of pairs in the created key/value vector
struct kvvec_buf* kvvec2buf ( struct kvvec kvv,
char  kv_sep,
char  pair_sep,
int  overalloc 
) [read]

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:
kvv The key/value vector to convert
kv_sep Character separating keys and their values
pair_sep Character separating key/value pairs
overalloc Integer 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
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:
kvv The key/value vector to add this key/value pair to
key The key
keylen Length of the key
value The value
valuelen Length of the value
Returns:
0 on success, < 0 on errors
unsigned int kvvec_capacity ( struct kvvec kvv  ) 

Return remaining storage capacity of key/value vector.

Parameters:
[in] kvv The key/value vector to check
Returns:
Number of key/value pairs that can be stored without growing
struct kvvec* kvvec_create ( int  hint  )  [read]

Create a key/value vector.

Parameters:
hint Number of key/value pairs we expect to store
Returns:
Pointer to a struct kvvec, properly initialized
int kvvec_destroy ( struct kvvec kvv,
int  flags 
)

Destroy a key/value vector.

Parameters:
kvv The key/value vector to destroy
flags or'ed combination of KVVEC_FREE_{KEYS,VALUES}, or KVVEC_FREE_ALL
Returns:
0 on success, < 0 on errors
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:
kvv The key/value vector to walk
arg Extra argument to the callback function
callback Callback function
Returns:
0 on success, < 0 on errors
void kvvec_free_kvpairs ( struct kvvec kvv,
int  flags 
)

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

Parameters:
kvv The key/value vector to operate on
flags flags or'ed combination of KVVEC_FREE_{KEYS,VALUES}, or KVVEC_FREE_ALL
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:
kvv The key/value vector to grow
hint The amount of key/value slots we should grow by
Returns:
0 on success, < 0 on errors
struct kvvec* kvvec_init ( struct kvvec kvv,
int  hint 
) [read]

Initialize a previously allocated key/value vector.

Parameters:
kvv The key/value vector to initialize
hint Number of key/value pairs we expect to store
Returns:
Pointer to a struct kvvec, properly initialized
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] kvv The key/value vector to resize
[in] size The size to grow to
Returns:
0 on success, < 0 on errors
int kvvec_sort ( struct kvvec kvv  ) 

Sort a key/value vector alphabetically by key name.

Parameters:
kvv The key/value vector to sort
Returns:
0
 All Data Structures Files Functions Variables Typedefs Defines

Generated on 24 Nov 2017 for Nagios by  doxygen 1.6.1