libt3config
Data Structures | Macros | Typedefs | Enumerations | Functions
Functions, constants and enums.

These are the functions and associated constants and enums for manipulating configuration data. More...

Data Structures

struct  t3_config_error_t
 A structure representing an error, with line number. More...
 
struct  t3_config_opts_t
 Options struct used when reading a file. More...
 
struct  t3_config_schema_t
 An opaque struct representing a schema. More...
 
struct  t3_config_t
 An opaque struct representing a config or sub-config. More...
 

Macros

#define T3_CONFIG_VERSION
 The version of libt3config encoded as a single integer. More...
 

Typedefs

typedef char t3_bool
 A boolean type that does not clash with C++ or C99 bool. More...
 

Enumerations

enum  { t3_false, t3_true }
 Values for t3_bool, a boolean type that does not clash with C++ or C99 bool. More...
 
enum  t3_config_type_t {
  T3_CONFIG_NONE, T3_CONFIG_BOOL, T3_CONFIG_INT, T3_CONFIG_STRING,
  T3_CONFIG_NUMBER, T3_CONFIG_LIST, T3_CONFIG_SECTION, T3_CONFIG_PLIST
}
 Types of values that can be stored in a config. More...
 
enum  t3_config_xdg_dirs_t { T3_CONFIG_XDG_CONFIG_HOME, T3_CONFIG_XDG_DATA_HOME, T3_CONFIG_XDG_CACHE_HOME, T3_CONFIG_XDG_RUNTIME_DIR }
 Constants for t3_config_xdg_open_read and t3_config_xdg_open_write. More...
 

Functions

int t3_config_add_bool (t3_config_t *config, const char *name, t3_bool value)
 Add (or overwrite) a boolean value to a (sub-)config. More...
 
int t3_config_add_existing (t3_config_t *config, const char *name, t3_config_t *value)
 Add (or overwrite) an existing value to the (sub-)config. More...
 
int t3_config_add_int (t3_config_t *config, const char *name, t3_config_int_t value)
 Add (or overwrite) an integer value to a (sub-)config. More...
 
int t3_config_add_int64 (t3_config_t *config, const char *name, int64_t value)
 Add (or overwrite) an integer value to a (sub-)config. More...
 
t3_config_tt3_config_add_list (t3_config_t *config, const char *name, int *error)
 Add (or overwrite) a list to the (sub-)config. More...
 
int t3_config_add_number (t3_config_t *config, const char *name, double value)
 Add (or overwrite) an floating point number value to a (sub-)config. More...
 
t3_config_tt3_config_add_plist (t3_config_t *config, const char *name, int *error)
 Add (or overwrite) a plist to the (sub-)config. More...
 
t3_config_tt3_config_add_section (t3_config_t *config, const char *name, int *error)
 Add (or overwrite) a section to the (sub-)config. More...
 
int t3_config_add_string (t3_config_t *config, const char *name, const char *value)
 Add (or overwrite) a string value to a (sub-)config. More...
 
t3_bool t3_config_close_write (t3_config_write_file_t *file, t3_bool cancel_rename, t3_bool force)
 Close a t3_config_write_file_t returned by t3_config_open_write or t3_config_xdg_open_write. More...
 
void t3_config_delete (t3_config_t *config)
 Free all memory used by a (sub-)config. More...
 
void t3_config_delete_schema (t3_config_schema_t *schema)
 Free all memory used by schema. More...
 
void t3_config_erase (t3_config_t *config, const char *name)
 Erase an item from a (sub-)config. More...
 
void t3_config_erase_from_list (t3_config_t *list, t3_config_t *item)
 Erase an item from a (sub-)config or list. More...
 
t3_config_tt3_config_find (const t3_config_t *config, t3_bool(*predicate)(const t3_config_t *, const void *), const void *data, t3_config_t *start_from)
 Find a specific value in a section or list. More...
 
t3_config_tt3_config_get (const t3_config_t *config, const char *name)
 Retrieve a sub-config. More...
 
t3_bool t3_config_get_bool (const t3_config_t *config)
 Get the boolean value from a config with T3_CONFIG_BOOL type. More...
 
t3_bool t3_config_get_bool_dflt (const t3_config_t *config, t3_bool dflt)
 Get the boolean value from a config with T3_CONFIG_BOOL type. More...
 
const char * t3_config_get_file_name (const t3_config_t *config)
 Get the file name in which the (sub-)configuration item was defined. More...
 
t3_config_int_t t3_config_get_int (const t3_config_t *config)
 Get the integer value from a config with T3_CONFIG_INT type. More...
 
int64_t t3_config_get_int64 (const t3_config_t *config)
 Get the integer value from a config with T3_CONFIG_INT type. More...
 
int64_t t3_config_get_int64_dflt (const t3_config_t *config, int64_t dflt)
 Get the integer value from a config with T3_CONFIG_INT type. More...
 
t3_config_int_t t3_config_get_int_dflt (const t3_config_t *config, t3_config_int_t dflt)
 Get the integer value from a config with T3_CONFIG_INT type. More...
 
int t3_config_get_length (const t3_config_t *config)
 Get the number of elements in a section or list. More...
 
int t3_config_get_line (const t3_config_t *config)
 Get the line number at which the (sub-)config was defined. More...
 
int t3_config_get_line_number (const t3_config_t *config)
 Get the line number at which the (sub-)configuration item was defined. More...
 
const char * t3_config_get_name (const t3_config_t *config)
 Get the name of the (sub-)config. More...
 
t3_config_tt3_config_get_next (const t3_config_t *config)
 Get the next sub-config from a section or list. More...
 
double t3_config_get_number (const t3_config_t *config)
 Get the floating point value from a config with T3_CONFIG_NUMBER type. More...
 
double t3_config_get_number_dflt (const t3_config_t *config, double dflt)
 Get the floating point value from a config with T3_CONFIG_NUMBER type. More...
 
const char * t3_config_get_string (const t3_config_t *config)
 Get the string value from a config with T3_CONFIG_STRING type. More...
 
const char * t3_config_get_string_dflt (const t3_config_t *config, const char *dflt)
 Get the string value from a config with T3_CONFIG_STRING type. More...
 
t3_config_type_t t3_config_get_type (const t3_config_t *config)
 Get the type of a (sub-)config. More...
 
long t3_config_get_version (void)
 Get the value of T3_CONFIG_VERSION corresponding to the actual used library. More...
 
FILE * t3_config_get_write_file (t3_config_write_file_t *file)
 Get the FILE member of a t3_config_write_file_t returned by t3_config_open_write or t3_config_xdg_open_write. More...
 
t3_bool t3_config_is_list (const t3_config_t *config)
 Check if a (sub-)config is a T3_CONFIG_LIST or T3_CONFIG_PLIST. More...
 
t3_config_tt3_config_new (void)
 Create a new config. More...
 
FILE * t3_config_open_from_path (const char **path, const char *name, int flags)
 Open a file for reading using a search path. More...
 
t3_config_write_file_tt3_config_open_write (const char *file_name)
 Open a configuration file for writing. More...
 
t3_config_tt3_config_read_buffer (const char *buffer, size_t size, t3_config_error_t *error, const t3_config_opts_t *opts)
 Read a config from memory. More...
 
t3_config_tt3_config_read_file (FILE *file, t3_config_error_t *error, const t3_config_opts_t *opts)
 Read a config from a FILE. More...
 
t3_config_schema_tt3_config_read_schema_buffer (const char *buffer, size_t size, t3_config_error_t *error, const t3_config_opts_t *opts)
 Read a schema from memory. More...
 
t3_config_schema_tt3_config_read_schema_file (FILE *file, t3_config_error_t *error, const t3_config_opts_t *opts)
 Read a schema from a FILE. More...
 
int t3_config_set_list_type (t3_config_t *config, t3_config_type_t type)
 Set the type of list of an existing list-type (sub-)config. More...
 
const char * t3_config_strerror (int error)
 Get a string description for an error code. More...
 
char * t3_config_take_string (t3_config_t *config)
 Take ownership of the string value from a config with T3_CONFIG_STRING type. More...
 
t3_config_tt3_config_unlink (t3_config_t *config, const char *name)
 Unlink an item from a (sub-)config. More...
 
t3_config_tt3_config_unlink_from_list (t3_config_t *list, t3_config_t *item)
 Unlink an item from a (sub-)config or list. More...
 
t3_bool t3_config_validate (t3_config_t *config, const t3_config_schema_t *schema, t3_config_error_t *error, int flags)
 Validate that a config adheres to a schema. More...
 
int t3_config_write_file (t3_config_t *config, FILE *file)
 Write a config to a FILE. More...
 
t3_bool t3_config_xdg_close_write (t3_config_write_file_t *file, t3_bool cancel_rename, t3_bool force)
 Close a t3_config_write_file_t returned by t3_config_xdg_open_write. More...
 
FILE * t3_config_xdg_get_file (t3_config_write_file_t *file)
 Get the FILE member of a t3_config_write_file_t returned by t3_config_xdg_open_write. More...
 
char * t3_config_xdg_get_path (t3_config_xdg_dirs_t xdg_dir, const char *program_dir, size_t file_name_len)
 Get a variable containing a specific XDG directory path. More...
 
FILE * t3_config_xdg_open_read (t3_config_xdg_dirs_t xdg_dir, const char *program_dir, const char *file_name)
 Open a configuration file for reading in one of the XDG Base Directory Specification directories. More...
 
t3_config_write_file_tt3_config_xdg_open_write (t3_config_xdg_dirs_t xdg_dir, const char *program_dir, const char *file_name)
 Open a configuration file for writing in one of the XDG Base Directory Specification directories. More...
 
t3_bool t3_config_xdg_supported (void)
 Query whether this library instance supports the XDG Base Directory Specification support functions. More...
 

Flags for ::t3_config_opts_t.

#define T3_CONFIG_VERBOSE_ERROR
 Return extra information about the error in the t3_config_error_t struct. More...
 
#define T3_CONFIG_INCLUDE_DFLT
 Activate the default include file mechanism. More...
 
#define T3_CONFIG_INCLUDE_USER
 Activate the user-defined include file mechanism. More...
 
#define T3_CONFIG_ERROR_FILE_NAME
 Return the file name where the error occured in the t3_config_error_t struct. More...
 

Error codes (libt3config specific)

#define T3_ERR_OUT_OF_RANGE
 Error code: Value is out of range. More...
 
#define T3_ERR_PARSE_ERROR
 Error code: Parse error. More...
 
#define T3_ERR_DUPLICATE_KEY
 Error code: Key already exists. More...
 
#define T3_ERR_INVALID_CONSTRAINT
 Error code: Constraint is invalid. More...
 
#define T3_ERR_INVALID_KEY_TYPE
 Error code: The key has a different type than allowed by the schema. More...
 
#define T3_ERR_INVALID_KEY
 Error code: The key is not allowed here by the schema. More...
 
#define T3_ERR_CONSTRAINT_VIOLATION
 Error code: The configuration violates a constraint in the schema. More...
 
#define T3_ERR_RECURSIVE_TYPE
 Error code: The type definition refers to itself, either directly or indirectly. More...
 
#define T3_ERR_RECURSIVE_INCLUDE
 Error code: An included file includes itself, either directly or indirectly. More...
 

Flags for ::t3_config_open_from_path.

#define T3_CONFIG_SPLIT_PATH
 Search paths should first be split on colons or semi-colons (depending on the platform standard). More...
 
#define T3_CONFIG_CLEAN_NAME
 Only allow file names which are in the path. More...
 

Error codes (T3 generic)

#define T3_ERR_SUCCESS
 Error code: success.
 
#define T3_ERR_ERRNO
 Error code: see errno. More...
 
#define T3_ERR_EOF
 Error code: end of file reached. More...
 
#define T3_ERR_UNKNOWN
 Error code: unkown error. More...
 
#define T3_ERR_BAD_ARG
 Error code: bad argument. More...
 
#define T3_ERR_OUT_OF_MEMORY
 Error code: out of memory. More...
 
#define T3_ERR_TERMINFODB_NOT_FOUND
 Error code: no information found for the terminal in the terminfo database. More...
 
#define T3_ERR_HARDCOPY_TERMINAL
 Error code: the file descriptor is a hard-copy terminal. More...
 
#define T3_ERR_TERMINAL_TOO_LIMITED
 Error code: terminal provides too limited possibilities for the library to function. More...
 
#define T3_ERR_NO_TERM
 Error code: no terminal given and TERM environment variable not set. More...
 
#define T3_ERR_INTERNAL
 Error code: internal error in the library. More...
 
#define T3_WARN_MIN
 Warning code: the smallest value returned as warning. More...
 

Detailed Description

These are the functions and associated constants and enums for manipulating configuration data.

All functions for retrieving data from a config structure in the libt3config library allow a NULL value to be passed as their first parameter. This allows one to simply pass the result from for example t3_config_get to t3_config_get_string, without checking the result of the former. If the string is not present, the result of the combined call will simply yield the default value (NULL).

Macro Definition Documentation

◆ T3_CONFIG_CLEAN_NAME

#define T3_CONFIG_CLEAN_NAME

Only allow file names which are in the path.

This flag disallows use of .. to read files in directories above the directories in the path, and also disallows absolute file names.

◆ T3_CONFIG_ERROR_FILE_NAME

#define T3_CONFIG_ERROR_FILE_NAME

Return the file name where the error occured in the t3_config_error_t struct.

◆ T3_CONFIG_INCLUDE_DFLT

#define T3_CONFIG_INCLUDE_DFLT

Activate the default include file mechanism.

When using this flags, the dflt member of the t3_config_opts_t include_callback union must be filled in.

◆ T3_CONFIG_INCLUDE_USER

#define T3_CONFIG_INCLUDE_USER

Activate the user-defined include file mechanism.

When using this flags, the user member of the t3_config_opts_t include_callback union must be filled in.

◆ T3_CONFIG_SPLIT_PATH

#define T3_CONFIG_SPLIT_PATH

Search paths should first be split on colons or semi-colons (depending on the platform standard).

◆ T3_CONFIG_VERBOSE_ERROR

#define T3_CONFIG_VERBOSE_ERROR

Return extra information about the error in the t3_config_error_t struct.

◆ T3_CONFIG_VERSION

#define T3_CONFIG_VERSION

The version of libt3config encoded as a single integer.

The least significant 8 bits represent the patch level. The second 8 bits represent the minor version. The third 8 bits represent the major version.

At runtime, the value of T3_CONFIG_VERSION can be retrieved by calling t3_config_get_version.

◆ T3_ERR_BAD_ARG

#define T3_ERR_BAD_ARG

Error code: bad argument.

◆ T3_ERR_CONSTRAINT_VIOLATION

#define T3_ERR_CONSTRAINT_VIOLATION

Error code: The configuration violates a constraint in the schema.

◆ T3_ERR_DUPLICATE_KEY

#define T3_ERR_DUPLICATE_KEY

Error code: Key already exists.

◆ T3_ERR_EOF

#define T3_ERR_EOF

Error code: end of file reached.

◆ T3_ERR_ERRNO

#define T3_ERR_ERRNO

Error code: see errno.

◆ T3_ERR_HARDCOPY_TERMINAL

#define T3_ERR_HARDCOPY_TERMINAL

Error code: the file descriptor is a hard-copy terminal.

◆ T3_ERR_INTERNAL

#define T3_ERR_INTERNAL

Error code: internal error in the library.

◆ T3_ERR_INVALID_CONSTRAINT

#define T3_ERR_INVALID_CONSTRAINT

Error code: Constraint is invalid.

◆ T3_ERR_INVALID_KEY

#define T3_ERR_INVALID_KEY

Error code: The key is not allowed here by the schema.

◆ T3_ERR_INVALID_KEY_TYPE

#define T3_ERR_INVALID_KEY_TYPE

Error code: The key has a different type than allowed by the schema.

◆ T3_ERR_NO_TERM

#define T3_ERR_NO_TERM

Error code: no terminal given and TERM environment variable not set.

◆ T3_ERR_OUT_OF_MEMORY

#define T3_ERR_OUT_OF_MEMORY

Error code: out of memory.

◆ T3_ERR_OUT_OF_RANGE

#define T3_ERR_OUT_OF_RANGE

Error code: Value is out of range.

◆ T3_ERR_PARSE_ERROR

#define T3_ERR_PARSE_ERROR

Error code: Parse error.

◆ T3_ERR_RECURSIVE_INCLUDE

#define T3_ERR_RECURSIVE_INCLUDE

Error code: An included file includes itself, either directly or indirectly.

◆ T3_ERR_RECURSIVE_TYPE

#define T3_ERR_RECURSIVE_TYPE

Error code: The type definition refers to itself, either directly or indirectly.

◆ T3_ERR_TERMINAL_TOO_LIMITED

#define T3_ERR_TERMINAL_TOO_LIMITED

Error code: terminal provides too limited possibilities for the library to function.

◆ T3_ERR_TERMINFODB_NOT_FOUND

#define T3_ERR_TERMINFODB_NOT_FOUND

Error code: no information found for the terminal in the terminfo database.

◆ T3_ERR_UNKNOWN

#define T3_ERR_UNKNOWN

Error code: unkown error.

◆ T3_WARN_MIN

#define T3_WARN_MIN

Warning code: the smallest value returned as warning.

Typedef Documentation

◆ t3_bool

typedef char t3_bool

A boolean type that does not clash with C++ or C99 bool.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Values for t3_bool, a boolean type that does not clash with C++ or C99 bool.

Enumerator
t3_false 

False.

t3_true 

True.

◆ t3_config_type_t

Types of values that can be stored in a config.

Enumerator
T3_CONFIG_NONE 

Only used for uninitialized values, or as error value.

T3_CONFIG_BOOL 

Boolean value.

T3_CONFIG_INT 

Integer value, at least 32 bits wide.

T3_CONFIG_STRING 

String value.

T3_CONFIG_NUMBER 

Floating point value (double).

T3_CONFIG_LIST 

A list of un-named items.

T3_CONFIG_SECTION 

A list of named items.

T3_CONFIG_PLIST 

A list of un-named items, written using %<name> notation.

◆ t3_config_xdg_dirs_t

Constants for t3_config_xdg_open_read and t3_config_xdg_open_write.

Enumerator
T3_CONFIG_XDG_CONFIG_HOME 

Use the XDG configuration directory.

Defaults to $HOME/.config.

T3_CONFIG_XDG_DATA_HOME 

Use the XDG data directory.

Defaults to $HOME/.local/share.

T3_CONFIG_XDG_CACHE_HOME 

Use the XDG cache directory.

Defaults to $HOME/.cache.

T3_CONFIG_XDG_RUNTIME_DIR 

Use the XDG runtime directory.

Does not have a default.

Function Documentation

◆ t3_config_add_bool()

int t3_config_add_bool ( t3_config_t config,
const char *  name,
t3_bool  value 
)

Add (or overwrite) a boolean value to a (sub-)config.

Parameters
configThe (sub-)config to add to.
nameThe name under which to add the item, or NULL if adding to a list.
valueThe value to add.
Return values
T3_ERR_SUCCESSon successful addition.
T3_ERR_BAD_ARGif config is not a list or section, or name is not set correctly.
T3_ERR_OUT_OF_MEMORY.

If an item with the given name already exists, it is replaced by the new value. If necessary, memory used by sub-items or values is released prior to replacing the value, but after checking for argument validity.

◆ t3_config_add_existing()

int t3_config_add_existing ( t3_config_t config,
const char *  name,
t3_config_t value 
)

Add (or overwrite) an existing value to the (sub-)config.

The primary use of this function is to add complete sections created earlier from some source, or unlinked from elsewhere in the configuration. This should not be used to link the same configuration into the tree multiple times.

See t3_config_add_bool for details.

◆ t3_config_add_int()

int t3_config_add_int ( t3_config_t config,
const char *  name,
t3_config_int_t  value 
)

Add (or overwrite) an integer value to a (sub-)config.

See t3_config_add_bool for details.

Deprecated:
Use t3_config_add_int64 instead.

◆ t3_config_add_int64()

int t3_config_add_int64 ( t3_config_t config,
const char *  name,
int64_t  value 
)

Add (or overwrite) an integer value to a (sub-)config.

See t3_config_add_bool for details.

◆ t3_config_add_list()

t3_config_t* t3_config_add_list ( t3_config_t config,
const char *  name,
int *  error 
)

Add (or overwrite) a list to the (sub-)config.

Parameters
configThe (sub-)config to add to.
nameThe name under which to add the item, or NULL if adding to a list.
errorA pointer to the location to store an error value (or NULL).
Returns
A pointer to the newly added list, or NULL on error.

If an item with the given name already exists, it is replaced by the new list. If necessary, memory used by sub-items or values is released prior to replacing the value, but after checking for argument validity.

If config is NULL, an error of type T3_ERR_BAD_ARG is returned.

◆ t3_config_add_number()

int t3_config_add_number ( t3_config_t config,
const char *  name,
double  value 
)

Add (or overwrite) an floating point number value to a (sub-)config.

See t3_config_add_bool for details.

◆ t3_config_add_plist()

t3_config_t* t3_config_add_plist ( t3_config_t config,
const char *  name,
int *  error 
)

Add (or overwrite) a plist to the (sub-)config.

See t3_config_add_list for details.

◆ t3_config_add_section()

t3_config_t* t3_config_add_section ( t3_config_t config,
const char *  name,
int *  error 
)

Add (or overwrite) a section to the (sub-)config.

See t3_config_add_list for details.

◆ t3_config_add_string()

int t3_config_add_string ( t3_config_t config,
const char *  name,
const char *  value 
)

Add (or overwrite) a string value to a (sub-)config.

A copy of the string is stored in the (sub-)config. See t3_config_add_bool for further details.

◆ t3_config_close_write()

t3_bool t3_config_close_write ( t3_config_write_file_t file,
t3_bool  cancel_rename,
t3_bool  force 
)

Close a t3_config_write_file_t returned by t3_config_open_write or t3_config_xdg_open_write.

Parameters
fileThe t3_config_write_file_t to close.
cancel_renameBoolean indicating whether the temporary file should be renamed to the actual config file.
forceBoolean indicating whether to force file close on error.
Returns
A boolean indicating whether the close was successful.

The force parameter indicates whether the file should be closed and discared when an error is encountered. Errors may be an out of memory condition or failure of the rename to the intended file name. If force is t3_true, the file will be closed and discared on error, but the returned value will still be t3_false to allow detection of the failed close.

◆ t3_config_delete()

void t3_config_delete ( t3_config_t config)

Free all memory used by a (sub-)config.

If you wish to remove a sub-config, either use t3_config_erase or t3_config_erase_from_list, or call t3_config_unlink or t3_config_unlink_from_list on the sub-config first.

◆ t3_config_delete_schema()

void t3_config_delete_schema ( t3_config_schema_t schema)

Free all memory used by schema.

◆ t3_config_erase()

void t3_config_erase ( t3_config_t config,
const char *  name 
)

Erase an item from a (sub-)config.

All memory related to the item and all sub-items is released.

◆ t3_config_erase_from_list()

void t3_config_erase_from_list ( t3_config_t list,
t3_config_t item 
)

Erase an item from a (sub-)config or list.

All memory related to the item and all sub-items is released.

◆ t3_config_find()

t3_config_t* t3_config_find ( const t3_config_t config,
t3_bool(*)(const t3_config_t *, const void *)  predicate,
const void *  data,
t3_config_t start_from 
)

Find a specific value in a section or list.

Parameters
configThe section or list to search.
predicateA function to call which determines whether an item in the section or list matches.
dataA pointer to user data which will be passed as the second argument to predicate.
start_fromA pointer to the last found item, or NULL to start from the beginning of the list.
Returns
A pointer to the first item for which predicate returned t3_true, or NULL of none was found.

This function allows one to easily find an item matching a predicate in a section or list. It can also be used to find all matching items, by simply passing the result of the last call as the start_from parameter until the function returns NULL.

◆ t3_config_get()

t3_config_t* t3_config_get ( const t3_config_t config,
const char *  name 
)

Retrieve a sub-config.

Parameters
configThe (sub-)config to retrieve from.
nameThe name of the sub-config to retrieve, or NULL for the first sub-config.
Returns
The requested sub-config, or NULL if no sub-config exists with the given name.

This function can be used both to retrieve a named sub-config, or to get the first sub-config for iteration over all items in this (sub-)config. For lists, use NULL for the name parameter to get the first item in the list, and use t3_config_get_next to retrieve further items.

◆ t3_config_get_bool()

t3_bool t3_config_get_bool ( const t3_config_t config)

Get the boolean value from a config with T3_CONFIG_BOOL type.

Returns
The boolean value of config, or t3_false if config is NULL or not of type T3_CONFIG_BOOL.

◆ t3_config_get_bool_dflt()

t3_bool t3_config_get_bool_dflt ( const t3_config_t config,
t3_bool  dflt 
)

Get the boolean value from a config with T3_CONFIG_BOOL type.

Returns
The boolean value of config, or dflt config is NULL or not of type T3_CONFIG_BOOL.

◆ t3_config_get_file_name()

const char* t3_config_get_file_name ( const t3_config_t config)

Get the file name in which the (sub-)configuration item was defined.

This function will return NULL if it was not created in a file, or it was defined in the file/buffer passed to t3_config_read_file or t3_config_read_buffer.

◆ t3_config_get_int()

t3_config_int_t t3_config_get_int ( const t3_config_t config)

Get the integer value from a config with T3_CONFIG_INT type.

Returns
The integer value of config, or 0 if config is NULL or not of type T3_CONFIG_INT.
Deprecated:
Use t3_config_get_int64 instead.

◆ t3_config_get_int64()

int64_t t3_config_get_int64 ( const t3_config_t config)

Get the integer value from a config with T3_CONFIG_INT type.

Returns
The integer value of config, or 0 if config is NULL or not of type T3_CONFIG_INT.

◆ t3_config_get_int64_dflt()

int64_t t3_config_get_int64_dflt ( const t3_config_t config,
int64_t  dflt 
)

Get the integer value from a config with T3_CONFIG_INT type.

Returns
The integer value of config, or dflt if config is NULL or not of type T3_CONFIG_INT.

◆ t3_config_get_int_dflt()

t3_config_int_t t3_config_get_int_dflt ( const t3_config_t config,
t3_config_int_t  dflt 
)

Get the integer value from a config with T3_CONFIG_INT type.

Returns
The integer value of config, or dflt if config is NULL or not of type T3_CONFIG_INT.
Deprecated:
Use t3_config_get_int64_dflt instead.

◆ t3_config_get_length()

int t3_config_get_length ( const t3_config_t config)

Get the number of elements in a section or list.

If config is NULL or not a section or list, this function will return 0.

◆ t3_config_get_line()

int t3_config_get_line ( const t3_config_t config)

Get the line number at which the (sub-)config was defined.

◆ t3_config_get_line_number()

int t3_config_get_line_number ( const t3_config_t config)

Get the line number at which the (sub-)configuration item was defined.

◆ t3_config_get_name()

const char* t3_config_get_name ( const t3_config_t config)

Get the name of the (sub-)config.

Retrieves the name of the config, or NULL if config is part of a list or the top-level config.

◆ t3_config_get_next()

t3_config_t* t3_config_get_next ( const t3_config_t config)

Get the next sub-config from a section or list.

Returns
A pointer to the next sub-config or NULL if there is no next sub-config.

This can be used in combination with t3_config_get to iterate over a list or section:

void iterate(t3_config_t *config) {
t3_config_t *item;
for (item = t3_config_get(config, NULL); item != NULL; item = t3_config_get_next(item)) {
// Do something with item.
}
}

◆ t3_config_get_number()

double t3_config_get_number ( const t3_config_t config)

Get the floating point value from a config with T3_CONFIG_NUMBER type.

Returns
The floating point value of config, or 0.0 if config is NULL or not of type T3_CONFIG_NUMBER.

◆ t3_config_get_number_dflt()

double t3_config_get_number_dflt ( const t3_config_t config,
double  dflt 
)

Get the floating point value from a config with T3_CONFIG_NUMBER type.

Returns
The floating point value of config, or dflt if config is NULL or not of type T3_CONFIG_NUMBER.

◆ t3_config_get_string()

const char* t3_config_get_string ( const t3_config_t config)

Get the string value from a config with T3_CONFIG_STRING type.

Returns
The string value of config, or NULL if config is NULL or not of type T3_CONFIG_STRING.

◆ t3_config_get_string_dflt()

const char* t3_config_get_string_dflt ( const t3_config_t config,
const char *  dflt 
)

Get the string value from a config with T3_CONFIG_STRING type.

Returns
The string value of config, or dflt if config is NULL or not of type T3_CONFIG_STRING.

◆ t3_config_get_type()

t3_config_type_t t3_config_get_type ( const t3_config_t config)

Get the type of a (sub-)config.

See t3_config_type_t for possible types.

◆ t3_config_get_version()

long t3_config_get_version ( void  )

Get the value of T3_CONFIG_VERSION corresponding to the actual used library.

Returns
The value of T3_CONFIG_VERSION.

This function can be useful to determine at runtime what version of the library was linked to the program. Although currently there are no known uses for this information, future library additions may prompt library users to want to operate differently depending on the available features.

◆ t3_config_get_write_file()

FILE* t3_config_get_write_file ( t3_config_write_file_t file)

Get the FILE member of a t3_config_write_file_t returned by t3_config_open_write or t3_config_xdg_open_write.

◆ t3_config_is_list()

t3_bool t3_config_is_list ( const t3_config_t config)

Check if a (sub-)config is a T3_CONFIG_LIST or T3_CONFIG_PLIST.

◆ t3_config_new()

t3_config_t* t3_config_new ( void  )

Create a new config.

Returns
A pointer to the new config or NULL if out of memory. Each config is a section. This function creates an empty section.

◆ t3_config_open_from_path()

FILE* t3_config_open_from_path ( const char **  path,
const char *  name,
int  flags 
)

Open a file for reading using a search path.

Parameters
pathA NULL terminated array of search paths.
nameThe name of the file to open.
flagsA set of flags influencing the behaviour, or 0 for defaults.
Returns
A file opened for reading, or NULL on error.

On error, errno is set. Possible flags for opts are: T3_CONFIG_SPLIT_PATH.

◆ t3_config_open_write()

t3_config_write_file_t* t3_config_open_write ( const char *  file_name)

Open a configuration file for writing.

Parameters
file_nameThe name of the configuration file to open.
Returns
NULL is returned on error and errno is set.

This function opens a temporary file, associated with a named configuration file. This temporary file is then renamed to the configuration file on close. Using this method ensures that the configuration file is always intact, even when the program is for some reason halted in mid-write.

◆ t3_config_read_buffer()

t3_config_t* t3_config_read_buffer ( const char *  buffer,
size_t  size,
t3_config_error_t error,
const t3_config_opts_t opts 
)

Read a config from memory.

Parameters
bufferThe buffer to parse.
sizeThe size of the buffer.
errorA pointer to the location to store an error value (or NULL).
optsA pointer to a struct containing options, or NULL to use the defaults.
Returns
A pointer to the new config or NULL on error.

◆ t3_config_read_file()

t3_config_t* t3_config_read_file ( FILE *  file,
t3_config_error_t error,
const t3_config_opts_t opts 
)

Read a config from a FILE.

Parameters
fileThe FILE to read from.
errorA pointer to the location to store an error value (or NULL).
optsA pointer to a struct containing options, or NULL to use the defaults.
Returns
A pointer to the new config or NULL on error.

◆ t3_config_read_schema_buffer()

t3_config_schema_t* t3_config_read_schema_buffer ( const char *  buffer,
size_t  size,
t3_config_error_t error,
const t3_config_opts_t opts 
)

Read a schema from memory.

Parameters
bufferThe buffer to parse.
sizeThe size of the buffer.
errorA pointer to the location to store an error value (or NULL).
optsA pointer to a struct containing options, or NULL to use the defaults.
Returns
A pointer to the new schema or NULL on error.

◆ t3_config_read_schema_file()

t3_config_schema_t* t3_config_read_schema_file ( FILE *  file,
t3_config_error_t error,
const t3_config_opts_t opts 
)

Read a schema from a FILE.

Parameters
fileThe FILE to read from.
errorA pointer to the location to store an error value (or NULL).
optsA pointer to a struct containing options, or NULL to use the defaults.
Returns
A pointer to the new schema or NULL on error.

◆ t3_config_set_list_type()

int t3_config_set_list_type ( t3_config_t config,
t3_config_type_t  type 
)

Set the type of list of an existing list-type (sub-)config.

◆ t3_config_strerror()

const char* t3_config_strerror ( int  error)

Get a string description for an error code.

Parameters
errorThe error code returned by a function in libt3config.
Returns
An internationalized string description for the error code.

◆ t3_config_take_string()

char* t3_config_take_string ( t3_config_t config)

Take ownership of the string value from a config with T3_CONFIG_STRING type.

Returns
The string value of config, or NULL if config is NULL or not of type T3_CONFIG_STRING.

After calling this function, the type of the config will be set to T3_CONFIG_NONE.

◆ t3_config_unlink()

t3_config_t* t3_config_unlink ( t3_config_t config,
const char *  name 
)

Unlink an item from a (sub-)config.

◆ t3_config_unlink_from_list()

t3_config_t* t3_config_unlink_from_list ( t3_config_t list,
t3_config_t item 
)

Unlink an item from a (sub-)config or list.

◆ t3_config_validate()

t3_bool t3_config_validate ( t3_config_t config,
const t3_config_schema_t schema,
t3_config_error_t error,
int  flags 
)

Validate that a config adheres to a schema.

Parameters
configThe config to validate.
schemaThe schema to validate against.
errorA pointer to the location to store an error value (or NULL).
flagsA set of flags influencing the behaviour, or 0 for defaults.
Returns
t3_true if the config is adheres to the schema, t3_false otherwise.

Currently, only the flag T3_CONFIG_VERBOSE_ERROR can be used.

◆ t3_config_write_file()

int t3_config_write_file ( t3_config_t config,
FILE *  file 
)

Write a config to a FILE.

Parameters
configThe config to write.
fileThe FILE to write to.
Returns
Either T3_ERR_ERRNO or T3_ERR_SUCCESS

◆ t3_config_xdg_close_write()

t3_bool t3_config_xdg_close_write ( t3_config_write_file_t file,
t3_bool  cancel_rename,
t3_bool  force 
)

Close a t3_config_write_file_t returned by t3_config_xdg_open_write.

Parameters
fileThe t3_config_write_file_t to close.
cancel_renameBoolean indicating whether the temporary file should be renamed to the actual config file.
forceBoolean indicating whether to force file close on error.
Returns
A boolean indicating whether the close was successful.

The force parameter indicates whether the file should be closed and discared when an error is encountered. Errors may be an out of memory condition or failure of the rename to the intended file name. If force is t3_true, the file will be closed and discared on error, but the returned value will still be t3_false to allow detection of the failed close.

Deprecated:
Use t3_config_close_write instead.

◆ t3_config_xdg_get_file()

FILE* t3_config_xdg_get_file ( t3_config_write_file_t file)

Get the FILE member of a t3_config_write_file_t returned by t3_config_xdg_open_write.

Deprecated:
Use t3_config_get_write_file instead.

◆ t3_config_xdg_get_path()

char* t3_config_xdg_get_path ( t3_config_xdg_dirs_t  xdg_dir,
const char *  program_dir,
size_t  file_name_len 
)

Get a variable containing a specific XDG directory path.

Parameters
xdg_dirA constant indicating which XDG dir to use.
program_dirAn optional (but recommended) directory within the XDG dir to use.
file_name_lenThe length of the file name that will be appended to this path.
Returns
A string containing the path, or NULL on error.

The returned string must be free'd. The file_name_len parameter allows extra memory to be allocated in the string to allow appending a slash and a string of length file_name_len.

◆ t3_config_xdg_open_read()

FILE* t3_config_xdg_open_read ( t3_config_xdg_dirs_t  xdg_dir,
const char *  program_dir,
const char *  file_name 
)

Open a configuration file for reading in one of the XDG Base Directory Specification directories.

Parameters
xdg_dirA constant indicating which XDG dir to use.
program_dirAn optional (but recommended) directory within the XDG dir to use.
file_nameThe name of the configuration file to open.
Returns
NULL is returned on error and errno is set.

This function opens a file in one of the XDG Base Directory Specification directories. It uses the XDG_* environment variables to find the files, and uses the fallbacks as specified in the standard if the environment variables are not set.

◆ t3_config_xdg_open_write()

t3_config_write_file_t* t3_config_xdg_open_write ( t3_config_xdg_dirs_t  xdg_dir,
const char *  program_dir,
const char *  file_name 
)

Open a configuration file for writing in one of the XDG Base Directory Specification directories.

Parameters
xdg_dirA constant indicating which XDG dir to use.
program_dirAn optional (but recommended) directory within the XDG dir to use.
file_nameThe name of the configuration file to open.
Returns
NULL is returned on error and errno is set.

This function opens a temporary file in one of the XDG Base Directory Specification directories, associated with a named configuration file. This temporary file is then renamed to the configuration file on close. Using this method ensures that the configuration file is always intact, even when the program is for some reason halted in mid-write.

This function uses the XDG_* environment variables to find the files, and uses the fallbacks as specified in the standard if the environment variables are not set.

◆ t3_config_xdg_supported()

t3_bool t3_config_xdg_supported ( void  )

Query whether this library instance supports the XDG Base Directory Specification support functions.