conf.h File Reference

#include <stdio.h>
#include <stdint.h>
#include "helpers.h"
#include "types.h"
#include "avl.h"

Include dependency graph for conf.h:

Go to the source code of this file.

Functions
conf_t *	conf_create_empty (void)
conf_t *	conf_create_copy (const conf_t *conf2)
void	conf_free (conf_t *conf)
conf_t *	conf_read_file (const char *filename, int *errline)
conf_t *	conf_read (FILE *fp, int *errline)
conf_t *	conf_read2 (void *fp, int *errline, bool_t compressed)
conf_t *	conf_read_buf (const void *buf, size_t cap, int *errline)
bool_t	conf_write_file (const conf_t *conf, const char *filename)
bool_t	conf_write_file2 (const conf_t *conf, const char *filename, bool_t compressed)
bool_t	conf_write (const conf_t *conf, FILE *fp)
size_t	conf_write_buf (const conf_t *conf, void *buf, size_t cap)
void	conf_merge (const conf_t *conf_from, conf_t *conf_to)
bool_t	conf_get_str (const conf_t *conf, const char *key, const char **value)
bool_t	conf_get_i (const conf_t *conf, const char *key, int *value)
bool_t	conf_get_lli (const conf_t *conf, const char *key, long long *value)
bool_t	conf_get_f (const conf_t *conf, const char *key, float *value)
bool_t	conf_get_d (const conf_t *conf, const char *key, double *value)
bool_t	conf_get_da (const conf_t *conf, const char *key, double *value)
bool_t	conf_get_b (const conf_t *conf, const char *key, bool_t *value)
size_t	conf_get_data (const conf_t *conf, const char *key, void *buf, size_t cap)
void	conf_set_str (conf_t *conf, const char *key, const char *value)
void	conf_set_i (conf_t *conf, const char *key, int value)
void	conf_set_lli (conf_t *conf, const char *key, long long value)
void	conf_set_f (conf_t *conf, const char *key, float value)
void	conf_set_d (conf_t *conf, const char *key, double value)
void	conf_set_da (conf_t *conf, const char *key, double value)
void	conf_set_b (conf_t *conf, const char *key, bool_t value)
void	conf_set_data (conf_t *conf, const char *key, const void *buf, size_t sz)
bool_t	conf_get_str_v (const conf_t *conf, const char *fmt, const char **value,...)
bool_t	conf_get_i_v (const conf_t *conf, const char *fmt, int *value,...)
bool_t	conf_get_lli_v (const conf_t *conf, const char *fmt, long long *value,...)
bool_t	conf_get_f_v (const conf_t *conf, const char *fmt, float *value,...)
bool_t	conf_get_d_v (const conf_t *conf, const char *fmt, double *value,...)
bool_t	conf_get_da_v (const conf_t *conf, const char *fmt, double *value,...)
bool_t	conf_get_b_v (const conf_t *conf, const char *fmt, bool_t *value,...)
size_t	conf_get_data_v (const conf_t *conf, const char *fmt, void *buf, size_t cap,...)
void	conf_set_str_v (conf_t *conf, const char *fmt, const char *value,...)
void	conf_set_i_v (conf_t *conf, const char *fmt, int value,...)
void	conf_set_lli_v (conf_t *conf, const char *fmt, long long value,...)
void	conf_set_f_v (conf_t *conf, const char *fmt, double value,...)
void	conf_set_d_v (conf_t *conf, const char *fmt, double value,...)
void	conf_set_da_v (conf_t *conf, const char *fmt, double value,...)
void	conf_set_b_v (conf_t *conf, const char *fmt, bool_t value,...)
void	conf_set_data_v (conf_t *conf, const char *fmt, const void *buf, size_t sz,...)
bool_t	conf_walk (const conf_t *conf, const char **key, const char **value, void **cookie)

Detailed Description

This is a general-purpose configuration store. It's really just a key-value pair dictionary that can be read from and written to a file.

The file format is very simple, consisting of a simple sequence of lines like the following:

key = value

In addition to being able to return the full-text values of keys, this set functions also allows you to easily parse the data in a variety of formats (integers, floats, booleans, etc.). The file format also allows for comments, so it is usable as a user-written configuration parser. Lines beginning with "#" or "--" are automatically skipped.

Definition in file conf.h.

Function Documentation

conf_create_copy()

conf_t * conf_create_copy

(

const conf_t *

conf2

)

Creates a new configuration as a copy of an existing configuration.

Returns

A copy of conf2 which mustbe freed by the caller using conf_free().

Definition at line 100 of file conf.c.

conf_create_empty()

conf_t * conf_create_empty

(

void

)

Creates an empty configuration. Set values using conf_set_* and write to a file using conf_write_file() and similar functions. You must free the returned configuration using conf_free() when you are done with it.

Definition at line 87 of file conf.c.

conf_free()

void conf_free

(

conf_t *

conf

)

Frees a conf_t object and all of its internal resources.

Definition at line 142 of file conf.c.

conf_get_b()

bool_t conf_get_b	(	const conf_t *	conf,
		const char *	key,
		bool_t *	value
	)

Retrieves the boolean value of a configuration key. If found, the value is placed in value.

Returns

B_TRUE if the key was found, else B_FALSE.

Definition at line 850 of file conf.c.

conf_get_b_v()

bool_t conf_get_b_v	(	const conf_t *	conf,
		const char *	fmt,
		bool_t *	value,
			...
	)

Same as conf_get_b(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1268 of file conf.c.

conf_get_d()

bool_t conf_get_d	(	const conf_t *	conf,
		const char *	key,
		double *	value
	)

Retrieves the 64-bit float value of a configuration key. If found, the value is placed in value.

Returns

B_TRUE if the key was found, else B_FALSE.

Definition at line 764 of file conf.c.

conf_get_d_v()

bool_t conf_get_d_v	(	const conf_t *	conf,
		const char *	fmt,
		double *	value,
			...
	)

Same as conf_get_d(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1229 of file conf.c.

conf_get_da()

bool_t conf_get_da	(	const conf_t *	conf,
		const char *	key,
		double *	value
	)

Retrieves the 64-bit float value previously stored using conf_set_da. If found, the value is placed in value.

Due to a limitation in MinGW, we can't use 'a' here. Instead, we directly write the binary representation of the double value. Since IEEE754 is used on all our supported platforms, that makes it portable. As future-proofing for big endian platforms, we always enforce storing the value in LE.

Returns

B_TRUE if the key was found, else B_FALSE.

Definition at line 816 of file conf.c.

conf_get_da_v()

bool_t conf_get_da_v	(	const conf_t *	conf,
		const char *	fmt,
		double *	value,
			...
	)

Same as conf_get_da(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1242 of file conf.c.

conf_get_data()

size_t conf_get_data	(	const conf_t *	conf,
		const char *	key,
		void *	buf,
		size_t	cap
	)

Retrieves a binary buffer value of a configuration key.

Parameters

buf	The buffer which will be filled with the configuration data. You must pre-allocate the buffer appropriately to hold the data, otherwise it will be truncated.
cap	The capacity of buf in bytes. This function will never write more than cap bytes to buf. Use the return value of this function to determine if the value was truncated.

Returns

The number of bytes that would have been written to buf if it had been large enough to contain the entire value. If the key doesn't exist in the configuration, returns 0 instead. Example how to allocate an appropriately-sized buffer first, before retrieving the configuration data "for real":

size_t len = conf_get_data(conf, key, NULL, 0);
void *buf = safe_malloc(len);
if (conf_get_data(conf, key, buf, len) != 0) {
    ... use data ...
}

Definition at line 902 of file conf.c.

conf_get_data_v()

size_t conf_get_data_v	(	const conf_t *	conf,
		const char *	fmt,
		void *	buf,
		size_t	cap,
			...
	)

Same as conf_get_data(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1255 of file conf.c.

conf_get_f()

bool_t conf_get_f	(	const conf_t *	conf,
		const char *	key,
		float *	value
	)

Same as conf_get_d, but for float values.

Definition at line 786 of file conf.c.

conf_get_f_v()

bool_t conf_get_f_v	(	const conf_t *	conf,
		const char *	fmt,
		float *	value,
			...
	)

Same as conf_get_f(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1217 of file conf.c.

conf_get_i()

bool_t conf_get_i	(	const conf_t *	conf,
		const char *	key,
		int *	value
	)

Definition at line 724 of file conf.c.

conf_get_i_v()

bool_t conf_get_i_v	(	const conf_t *	conf,
		const char *	fmt,
		int *	value,
			...
	)

Same as conf_get_i(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1192 of file conf.c.

conf_get_lli()

bool_t conf_get_lli	(	const conf_t *	conf,
		const char *	key,
		long long *	value
	)

Retrieves the 64-bit int value of a configuration key. If found, the value is placed in value.

Returns

B_TRUE if the key was found, else B_FALSE.

Definition at line 744 of file conf.c.

conf_get_lli_v()

bool_t conf_get_lli_v	(	const conf_t *	conf,
		const char *	fmt,
		long long *	value,
			...
	)

Same as conf_get_lli(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1205 of file conf.c.

conf_get_str()

bool_t conf_get_str	(	const conf_t *	conf,
		const char *	key,
		const char **	value
	)

Retrieves the string value of a configuration key. If found, the value is placed in value.

Returns

B_TRUE if the key was found, else B_FALSE.

Definition at line 704 of file conf.c.

conf_get_str_v()

bool_t conf_get_str_v	(	const conf_t *	conf,
		const char *	fmt,
		const char **	value,
			...
	)

Same as conf_get_str(), but allows passing in a printf-formatted argument string in ‘fmt’ and a variable number of arguments following ‘value’ to construct the configuration key name dynamically.

Definition at line 1180 of file conf.c.

conf_merge()

void conf_merge	(	const conf_t *	conf_from,
		conf_t *	conf_to
	)

Given two configurations, takes all values in ‘conf_from’ and inserts them into ‘conf_to’, in essence, merging the two configurations. After this call, ‘conf_to’ will contain all the values present in ‘conf_from’, as well as any pre-existing values that were already in ‘conf_to’. If a value exists in both ‘conf_to’ and ‘conf_from’, the value in ‘conf_from’ replaces the value in ‘conf_to’.

Definition at line 119 of file conf.c.

conf_read()

conf_t * conf_read	(	FILE *	fp,
		int *	errline
	)

Parses a configuration from a file. The file is structured as a series of "key = value" lines. The parser understands "#" and "--" comments.

Returns

The parsed conf_t object, or NULL in case an error was found. If errline is not NULL, it is set to the line number where the error was encountered.

Use conf_free() to free the returned structure when you are done with it.

Definition at line 246 of file conf.c.

conf_read2()

conf_t * conf_read2	(	void *	fp,
		int *	errline,
		bool_t	compressed
	)

Parses a configuration from a file. The file is structured as a series of "key = value" lines. The parser understands "#" and "--" comments.

Returns

The parsed conf_t object, or NULL in case an error was found. If errline is not NULL, it is set to the line number where the error was encountered.

Use conf_free() to free the returned structure.

Definition at line 335 of file conf.c.

conf_read_buf()

conf_t * conf_read_buf	(	const void *	buf,
		size_t	cap,
		int *	errline
	)

Same as conf_read(), but takes an in-memory buffer containing the text of the configuration.

Parameters

buf	The memory buffer containing the configuration file text. The buffer DOESN'T need to be NUL-terminated.
cap	The number of bytes in buf.
errline	Optional return argument, which will be the filled with the failing line number, if a parsing error occurs.

Returns

The parsed conf_t object, or NULL in case an error was found. If errline is not NULL, it is set to the line number where the error was encountered.

Use conf_free() to free the returned structure.

Definition at line 385 of file conf.c.

conf_read_file()

conf_t * conf_read_file	(	const char *	filename,
		int *	errline
	)

Same as conf_read, but serves as a shorthand for reading directly from a file path on disk. If the file cannot be opened for reading and errline is not NULL, it will be set to -1.

Returns

The parsed configuration object, or NULL if reading failed. You must free the returned configuration using conf_free() when you are done with it.

Definition at line 174 of file conf.c.

conf_set_b()

void conf_set_b	(	conf_t *	conf,
		const char *	key,
		bool_t	value
	)

Same as conf_set_str() but with a bool_t value. Obviously this cannot remove a key, use conf_set_str(conf, key, NULL) for that.

Definition at line 1081 of file conf.c.

conf_set_b_v()

void conf_set_b_v	(	conf_t *	conf,
		const char *	fmt,
		bool_t	value,
			...
	)

Same as conf_set_b(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1361 of file conf.c.

conf_set_d()

void conf_set_d	(	conf_t *	conf,
		const char *	key,
		double	value
	)

Same as conf_set_str() but with a double value. Obviously this cannot remove a key, use conf_set_str(conf, key, NULL) for that.

Definition at line 1024 of file conf.c.

conf_set_d_v()

void conf_set_d_v	(	conf_t *	conf,
		const char *	fmt,
		double	value,
			...
	)

Same as conf_set_d(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1338 of file conf.c.

conf_set_da()

void conf_set_da	(	conf_t *	conf,
		const char *	key,
		double	value
	)

Same as conf_set_d(), but able to accurately represent the exact value of a double argument. Obviously this cannot remove a key, use conf_set_str(conf, key, NULL) for that.

Definition at line 1055 of file conf.c.

conf_set_da_v()

void conf_set_da_v	(	conf_t *	conf,
		const char *	fmt,
		double	value,
			...
	)

Same as conf_set_da(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1350 of file conf.c.

conf_set_data()

void conf_set_data	(	conf_t *	conf,
		const char *	key,
		const void *	buf,
		size_t	sz
	)

Same as conf_set_str(), but allows you to pass an arbitrary binary data buffer to be set for the configuration key.

Parameters

buf	The data buffer to set for the key's value. If you pass NULL here instead, the key-value pair will be removed (if present).
sz	The number of bytes in buf. If you pass 0 here instead, the key-value pair will be removed (if present).

Definition at line 1108 of file conf.c.

conf_set_data_v()

void conf_set_data_v	(	conf_t *	conf,
		const char *	fmt,
		const void *	buf,
		size_t	sz,
			...
	)

Same as conf_set_data(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1372 of file conf.c.

conf_set_f()

void conf_set_f	(	conf_t *	conf,
		const char *	key,
		float	value
	)

Same as conf_set_str() but with a float value. Obviously this cannot remove a key, use conf_set_str(conf, key, NULL) for that.

Definition at line 1039 of file conf.c.

conf_set_f_v()

void conf_set_f_v	(	conf_t *	conf,
		const char *	fmt,
		double	value,
			...
	)

Same as conf_set_f(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1327 of file conf.c.

conf_set_i()

void conf_set_i	(	conf_t *	conf,
		const char *	key,
		int	value
	)

Same as conf_set_str() but with an int value. Obviously this cannot remove a key, use conf_set_str(conf, key, NULL) for that.

Definition at line 992 of file conf.c.

conf_set_i_v()

void conf_set_i_v	(	conf_t *	conf,
		const char *	fmt,
		int	value,
			...
	)

Same as conf_set_i(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1304 of file conf.c.

conf_set_lli()

void conf_set_lli	(	conf_t *	conf,
		const char *	key,
		long long	value
	)

Same as conf_set_str() but with a long long value. Obviously this cannot remove a key, use conf_set_str(conf, key, NULL) for that.

Definition at line 1004 of file conf.c.

conf_set_lli_v()

void conf_set_lli_v	(	conf_t *	conf,
		const char *	fmt,
		long long	value,
			...
	)

Same as conf_set_lli(), but with dynamic name-construction as conf_get_str_v().

Definition at line 1316 of file conf.c.

conf_set_str()

void conf_set_str	(	conf_t *	conf,
		const char *	key,
		const char *	value
	)

Sets up a key-value pair in the conf_t structure with a string value.

Parameters

key	The key name for which to set the value. If the key already exists, it will be overwritten.
value	The value to set for the new key. If you pass NULL, this will instead remove the key-value pair (if present).

Definition at line 928 of file conf.c.

conf_set_str_v()

void conf_set_str_v	(	conf_t *	conf,
		const char *	fmt,
		const char *	value,
			...
	)

Definition at line 1293 of file conf.c.

conf_walk()

bool_t conf_walk	(	const conf_t *	conf,
		const char **	key,
		const char **	value,
		void **	cookie
	)

Walks all configuration key-value pairs. You must NOT add or remove key-value pairs in the configuration during the walk.

Caveat: this function skips data-type keys (created with conf_set_data()).

Parameters

cookie	A helper pointer so the function knows how far it has progressed. You MUST set it to NULL before the first call.
key	Return parameter, which will be filled with the next key it has found.
value	Return parameter, which will be filled with the next string value it has found.

Returns

B_TRUE if the function has found another key-value pair and returned them in key and value, orB_FALSE` if no more key-value have been found.

Proper usage of this function:

void *cookie = NULL;
const char *key, *value;
while (conf_walk(conf, &key, &value, &cookie)) {
    ... do something with key & value ...
}

Definition at line 1406 of file conf.c.

conf_write()

bool_t conf_write	(	const conf_t *	conf,
		FILE *	fp
	)

Writes a conf_t object to a file. Returns B_TRUE if the write was successful, B_FALSE otherwise.

Definition at line 677 of file conf.c.

conf_write_buf()

size_t conf_write_buf	(	const conf_t *	conf,
		void *	buf,
		size_t	cap
	)

Writes a conf_t object to an in-memory buffer.

Parameters

buf	The buffer into which to write the configuration. This must be sized sufficiently large to contain the entire configuration file. Please note that the written buffer is not explicitly NUL-terminated, so you mustn't treat it as a char string.
cap	Capacity of buf in bytes. This function will never write more than cap bytes, even if that means cutting the configuration file short. You should check the return value of the function and allocate enough space in buf to contain the entire configuration.

Returns

The number of bytes it would have taken to contain the entire configuration. Example how to allocate an appropriately-sized buffer first, before writing the configuration "for real":

size_t len = conf_write_buf(conf, NULL, 0);
void *buf = safe_malloc(len);
conf_write_buf(conf, buf, len);

Definition at line 543 of file conf.c.

conf_write_file()

bool_t conf_write_file	(	const conf_t *	conf,
		const char *	filename
	)

Same as conf_write(), but serves as a shorthand for writing directly to a file path on disk.

Definition at line 449 of file conf.c.

conf_write_file2()

bool_t conf_write_file2	(	const conf_t *	conf,
		const char *	filename,
		bool_t	compressed
	)

Same as conf_write_file(), but lets you specify whether the output should be Gzip-compressed.

Definition at line 459 of file conf.c.