Lely core libraries  2.3.4
config.h File Reference

This header file is part of the utilities library; it contains the configuration functions. More...

#include <lely/util/util.h>
#include <stddef.h>
Include dependency graph for config.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef struct __config config_t
 An opaque configuration type.
 
typedef void config_foreach_func_t(const char *section, const char *key, const char *value, void *data)
 The type of a function called by config_foreach() for each key in a configuration struct. More...
 

Enumerations

enum  { CONFIG_CASE = 1 << 0 }
 

Functions

config_tconfig_create (int flags)
 Creates a new configuration struct with an unnamed empty root section. More...
 
void config_destroy (config_t *config)
 Destroys a configuration struct. More...
 
size_t config_get_sections (const config_t *config, size_t n, const char **sections)
 Retrieves a list of section names from a configuration struct. More...
 
size_t config_get_keys (const config_t *config, const char *section, size_t n, const char **keys)
 Retrieves a list of key names from a section in a configuration struct. More...
 
const char * config_get (const config_t *config, const char *section, const char *key)
 Retrieves a key from a configuration struct. More...
 
const char * config_set (config_t *config, const char *section, const char *key, const char *value)
 Sets a key in or removes a key from a configuration struct. More...
 
void config_foreach (const config_t *config, config_foreach_func_t *func, void *data)
 Invokes a function for each key in a configuration struct. More...
 
size_t config_parse_ini_file (config_t *config, const char *filename)
 Parses an INI file and adds the keys to a configuration struct. More...
 
size_t config_parse_ini_text (config_t *config, const char *begin, const char *end, struct floc *at)
 Parses a string in INI-format and adds the keys to a configuration struct. More...
 
size_t config_print_ini_file (const config_t *config, const char *filename)
 Prints a configuration struct to an INI file. More...
 
size_t config_print_ini_text (const config_t *config, char **pbegin, char *end)
 Prints a configuration struct in INI-format to a memory buffer. More...
 

Detailed Description

This header file is part of the utilities library; it contains the configuration functions.

Author
J. S. Seldenthuis jseld.nosp@m.enth.nosp@m.uis@l.nosp@m.ely..nosp@m.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Definition in file config.h.

Typedef Documentation

◆ config_foreach_func_t

typedef void config_foreach_func_t(const char *section, const char *key, const char *value, void *data)

The type of a function called by config_foreach() for each key in a configuration struct.

Parameters
sectiona pointer to the name of the section
keya pointer to the name of the key.
valuea pointer to the value of the key.
dataa pointer to user-specified data.

Definition at line 56 of file config.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
CONFIG_CASE 

Section and key names are case-insensitive.

Definition at line 35 of file config.h.

Function Documentation

◆ config_create()

config_t* config_create ( int  flags)

Creates a new configuration struct with an unnamed empty root section.

Parameters
flagseither 0 or CONFIG_CASE.
Returns
a pointer to a new configuration struct, or NULL on error. In the latter case, the error number can be obtained with get_errc().
See also
config_destroy()

Definition at line 115 of file config.c.

◆ config_destroy()

void config_destroy ( config_t config)

Destroys a configuration struct.

See also
config_create()

Definition at line 140 of file config.c.

◆ config_get_sections()

size_t config_get_sections ( const config_t config,
size_t  n,
const char **  sections 
)

Retrieves a list of section names from a configuration struct.

Parameters
configa pointer to a configuration struct.
nthe maximum number of sections to return.
sectionsan array of at least n pointers (can be NULL). On success, *sections contains the pointers to the section names.
Returns
the total number of sections in the configuration struct (which may may be different from n).
See also
config_get_keys()

Definition at line 149 of file config.c.

◆ config_get_keys()

size_t config_get_keys ( const config_t config,
const char *  section,
size_t  n,
const char **  keys 
)

Retrieves a list of key names from a section in a configuration struct.

Parameters
configa pointer to a configuration struct.
sectiona pointer to the name of the section. If section is NULL or "", the root section is used instead.
nthe maximum number of sections to return.
keysan array of at least n pointers (can be NULL). On success, *keys contains the pointers to the key names.
Returns
the total number of keys in the section (which may may be different from n).
See also
config_get_sections()

Definition at line 166 of file config.c.

◆ config_get()

const char* config_get ( const config_t config,
const char *  section,
const char *  key 
)

Retrieves a key from a configuration struct.

Parameters
configa pointer to a configuration struct.
sectiona pointer to the name of the section. If section is NULL or "", the root section is used instead.
keya pointer to the name of the key.
Returns
a pointer to the value of the key, or NULL if not found.

Definition at line 193 of file config.c.

◆ config_set()

const char* config_set ( config_t config,
const char *  section,
const char *  key,
const char *  value 
)

Sets a key in or removes a key from a configuration struct.

Parameters
configa pointer to a configuration struct.
sectiona pointer to the name of the section. If section is NULL or "", the root section is used instead.
keya pointer to the name of the key. This name is duplicated on success, so the caller need not guarantee the lifetime of the string.
valuea pointer to the new value of the key. If value is NULL, the key is removed. Like key, the string is duplicated on success.
Returns
a pointer to the value (which will differ from value due to duplication), or NULL on error or when the key is deleted. In case of an error, the error number can be obtained with get_errc().

Definition at line 218 of file config.c.

◆ config_foreach()

void config_foreach ( const config_t config,
config_foreach_func_t func,
void *  data 
)

Invokes a function for each key in a configuration struct.

Parameters
configa pointer to a configuration struct.
funca pointer to the function to be invoked.
dataa pointer to user-specified data (can be NULL). data is passed as the last parameter to func.

Definition at line 238 of file config.c.

◆ config_parse_ini_file()

size_t config_parse_ini_file ( config_t config,
const char *  filename 
)

Parses an INI file and adds the keys to a configuration struct.

Returns
the number of characters read, or 0 on error. I/O and parsing errors are reported with diag_at().
See also
config_parse_ini_text()

Definition at line 50 of file config_ini.c.

◆ config_parse_ini_text()

size_t config_parse_ini_text ( config_t config,
const char *  begin,
const char *  end,
struct floc at 
)

Parses a string in INI-format and adds the keys to a configuration struct.

Parameters
configa pointer to a configuration struct.
begina pointer to the first character in the string.
enda pointer to one past the last character in the string (can be NULL if the string is null-terminated).
atan optional pointer to the file location of begin (used for diagnostic purposes). On exit, if at != NULL, *at points to one past the last character parsed.
Returns
the number of characters read. Parsing errors are reported with diag() and diag_at(), respectively.
See also
config_parse_ini_file()

Definition at line 78 of file config_ini.c.

◆ config_print_ini_file()

size_t config_print_ini_file ( const config_t config,
const char *  filename 
)

Prints a configuration struct to an INI file.

Returns
the number of characters written, or 0 on error. I/O errors are reported with diag().
See also
config_print_ini_text()

Definition at line 182 of file config_ini.c.

◆ config_print_ini_text()

size_t config_print_ini_text ( const config_t config,
char **  pbegin,
char *  end 
)

Prints a configuration struct in INI-format to a memory buffer.

Note that the output is not null-terminated.

Parameters
configa pointer to a configuration struct.
pbeginthe address of a pointer to the start of the buffer. If pbegin or *pbegin is NULL, nothing is written; Otherwise, on exit, *pbegin points to one past the last character written.
enda pointer to one past the last character in the buffer. If end is not NULL, at most end - *pbegin characters are written, and the output may be truncated.
Returns
the number of characters that would have been written had the buffer been sufficiently large.
See also
config_print_ini_file()

Definition at line 216 of file config_ini.c.