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_t *	t3_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_t *	t3_config_add_plist (t3_config_t config, const char name, int *error)
	Add (or overwrite) a plist to the (sub-)config. More...

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. 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_t *	t3_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_t *	t3_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_t *	t3_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_t *	t3_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_t *	t3_config_open_write (const char *file_name)
	Open a configuration file for writing. More...

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. More...

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`. More...

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. More...

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`. 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_t *	t3_config_unlink (t3_config_t config, const char name)
	Unlink an item from a (sub-)config. More...

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. 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_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. 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

enum 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

enum 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

config	The (sub-)config to add to.
name	The name under which to add the item, or `NULL` if adding to a list.
value	The value to add.

Return values

T3_ERR_SUCCESS	on successful addition.
T3_ERR_BAD_ARG	if `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

config	The (sub-)config to add to.
name	The name under which to add the item, or `NULL` if adding to a list.
error	A 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

file	The t3_config_write_file_t to close.
cancel_rename	Boolean indicating whether the temporary file should be renamed to the actual config file.
force	Boolean 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

config	The section or list to search.
predicate	A function to call which determines whether an item in the section or list matches.
data	A pointer to user data which will be passed as the second argument to `predicate`.
start_from	A 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

config	The (sub-)config to retrieve from.
name	The 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

path	A `NULL` terminated array of search paths.
name	The name of the file to open.
flags	A 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_name The 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

buffer	The buffer to parse.
size	The size of the buffer.
error	A pointer to the location to store an error value (or `NULL`).
opts	A 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

file	The `FILE` to read from.
error	A pointer to the location to store an error value (or `NULL`).
opts	A 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

buffer	The buffer to parse.
size	The size of the buffer.
error	A pointer to the location to store an error value (or `NULL`).
opts	A 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

file	The `FILE` to read from.
error	A pointer to the location to store an error value (or `NULL`).
opts	A 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

error The 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

config	The config to validate.
schema	The schema to validate against.
error	A pointer to the location to store an error value (or `NULL`).
flags	A 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

config	The config to write.
file	The `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

file	The t3_config_write_file_t to close.
cancel_rename	Boolean indicating whether the temporary file should be renamed to the actual config file.
force	Boolean 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_dir	A constant indicating which XDG dir to use.
program_dir	An optional (but recommended) directory within the XDG dir to use.
file_name_len	The 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_dir	A constant indicating which XDG dir to use.
program_dir	An optional (but recommended) directory within the XDG dir to use.
file_name	The 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_dir	A constant indicating which XDG dir to use.
program_dir	An optional (but recommended) directory within the XDG dir to use.
file_name	The 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.

Data Structures

Macros

Typedefs

Enumerations

Functions

Flags for ::t3_config_opts_t.

Error codes (libt3config specific)

Flags for ::t3_config_open_from_path.

Error codes (T3 generic)

Detailed Description

Macro Definition Documentation

◆ T3_CONFIG_CLEAN_NAME

◆ T3_CONFIG_ERROR_FILE_NAME

◆ T3_CONFIG_INCLUDE_DFLT

◆ T3_CONFIG_INCLUDE_USER

◆ T3_CONFIG_SPLIT_PATH

◆ T3_CONFIG_VERBOSE_ERROR

◆ T3_CONFIG_VERSION

◆ T3_ERR_BAD_ARG

◆ T3_ERR_CONSTRAINT_VIOLATION

◆ T3_ERR_DUPLICATE_KEY

◆ T3_ERR_EOF

◆ T3_ERR_ERRNO

◆ T3_ERR_HARDCOPY_TERMINAL

◆ T3_ERR_INTERNAL

◆ T3_ERR_INVALID_CONSTRAINT

◆ T3_ERR_INVALID_KEY

◆ T3_ERR_INVALID_KEY_TYPE

◆ T3_ERR_NO_TERM

◆ T3_ERR_OUT_OF_MEMORY

◆ T3_ERR_OUT_OF_RANGE

◆ T3_ERR_PARSE_ERROR

◆ T3_ERR_RECURSIVE_INCLUDE

◆ T3_ERR_RECURSIVE_TYPE

◆ T3_ERR_TERMINAL_TOO_LIMITED

◆ T3_ERR_TERMINFODB_NOT_FOUND

◆ T3_ERR_UNKNOWN

◆ T3_WARN_MIN

Typedef Documentation

◆ t3_bool

Enumeration Type Documentation

◆ anonymous enum

◆ t3_config_type_t

◆ t3_config_xdg_dirs_t

Function Documentation

◆ t3_config_add_bool()

◆ t3_config_add_existing()

◆ t3_config_add_int()

◆ t3_config_add_int64()

◆ t3_config_add_list()

◆ t3_config_add_number()

◆ t3_config_add_plist()

◆ t3_config_add_section()

◆ t3_config_add_string()

◆ t3_config_close_write()

◆ t3_config_delete()

◆ t3_config_delete_schema()

◆ t3_config_erase()

◆ t3_config_erase_from_list()

◆ t3_config_find()

◆ t3_config_get()

◆ t3_config_get_bool()

◆ t3_config_get_bool_dflt()

◆ t3_config_get_file_name()

◆ t3_config_get_int()

◆ t3_config_get_int64()

◆ t3_config_get_int64_dflt()

◆ t3_config_get_int_dflt()

◆ t3_config_get_length()

◆ t3_config_get_line()

◆ t3_config_get_line_number()

◆ t3_config_get_name()

◆ t3_config_get_next()

◆ t3_config_get_number()

◆ t3_config_get_number_dflt()

◆ t3_config_get_string()

◆ t3_config_get_string_dflt()

◆ t3_config_get_type()

◆ t3_config_get_version()

◆ t3_config_get_write_file()