canfigger.h File Reference

Public API for the Canfigger configuration file parser. More...

#include "canfigger_version.h"

Go to the source code of this file.

Data Structures
struct	attributes
	Internal iteration state for a node's attribute list. More...
struct	Canfigger
	A single node in the parsed configuration linked list. More...

Macros
#define	CANFIGGER_CHECK_VERSION(maj, min)
	Compile-time version check.

Enumerations
enum	canfigger_user_dir {   CANFIGGER_USER_DIR_DESKTOP , CANFIGGER_USER_DIR_DOWNLOAD , CANFIGGER_USER_DIR_TEMPLATES , CANFIGGER_USER_DIR_PUBLICSHARE ,   CANFIGGER_USER_DIR_DOCUMENTS , CANFIGGER_USER_DIR_MUSIC , CANFIGGER_USER_DIR_PICTURES , CANFIGGER_USER_DIR_VIDEOS }
	The well-known user directories, as named by the XDG user directories specification. More...

Functions
struct Canfigger *	canfigger_parse_file (const char *file, const int delimiter)
	Parse a configuration file into a linked list of key-value nodes.
void	canfigger_free_current_key_node_advance (struct Canfigger **node)
	Free the current node and advance the list pointer to the next node.
void	canfigger_free_current_attr_str_advance (struct attributes *attributes, char **attr)
	Free the current attribute string and advance to the next attribute.
void	canfigger_free_list (struct Canfigger **node)
	Free all remaining nodes in the list.
char *	canfigger_config_dir (const char *appname)
	Return the platform config directory for an application.
char *	canfigger_config_file (const char *filename)
	Return the path to a config file in the platform base config directory.
char *	canfigger_data_dir (const char *appname)
	Return the platform data directory for an application.
char *	canfigger_cache_dir (const char *appname)
	Return the platform cache directory for an application.
char *	canfigger_state_dir (const char *appname)
	Return the platform state directory for an application.
char *	canfigger_runtime_dir (const char *appname)
	Return the runtime directory for an application, or NULL.
char **	canfigger_config_dirs (void)
	Return the system config search path, most important first.
char **	canfigger_data_dirs (void)
	Return the system data search path, most important first.
char *	canfigger_find_config_file (const char *appname, const char *filename)
	Find an existing config file along the full config search path.
char *	canfigger_user_dir (enum canfigger_user_dir which)
	Return one of the user's well-known directories.
void	canfigger_free_dirs (char **dirs)
	Free an array returned by canfigger_config_dirs() or canfigger_data_dirs().
char *	canfigger_path_join (const char *dir, const char *file)
	Join a directory path and a filename with the platform separator.

Detailed Description

Public API for the Canfigger configuration file parser.

Canfigger parses plain-text configuration files into a singly-linked list of key-value nodes. Each node may also carry a list of attributes — extra comma-separated (or user-specified delimiter) fields that follow the value on the same line.

File format (one entry per line):

key = value
key = value, attr1, attr2
key = list, item1, item2, item3
# comment lines are ignored
[section headers are ignored]

The = sign separates the key from the value. The delimiter character (passed to canfigger_parse_file()) separates the value from the first attribute, and each subsequent attribute from the next. A UTF-8 BOM at the start of the file is silently skipped.

Typical usage:

struct Canfigger *list = canfigger_parse_file("app.conf", ',');
while (list) {
  // use list->key and list->value
  canfigger_free_current_key_node_advance(&list);
}

Windows note. The path helpers return the ANSI form of a path. On a system whose active code page cannot represent the user's profile path - a non-ASCII account name, on a system not set to UTF-8 - they return NULL rather than a path that will not open. An application that ships a UTF-8 active-code-page manifest (Windows 10 1903 and later) is unaffected.

Part of canfigger (https://github.com/andy5995/canfigger).

Definition in file canfigger.h.

---

Data Structure Documentation

attributes

struct attributes

Internal iteration state for a node's attribute list.

This struct is allocated and owned by the library. Callers should not read or modify its fields directly; use canfigger_free_current_attr_str_advance() to iterate.

Definition at line 110 of file canfigger.h.

Data Fields
char *	current
char *	iter_ptr
char *	str

Canfigger

struct Canfigger

A single node in the parsed configuration linked list.

Each node represents one key-value entry from the configuration file. Nodes are heap-allocated by canfigger_parse_file() and must be freed with canfigger_free_current_key_node_advance() or canfigger_free_list().

Definition at line 132 of file canfigger.h.

Data Fields
struct attributes *	attributes
char *	key
struct Canfigger *	next
char *	value

Macro Definition Documentation

CANFIGGER_CHECK_VERSION

#define CANFIGGER_CHECK_VERSION	(		maj,
			min
	)

Value:

  (CANFIGGER_VERSION_MAJOR > (maj) || \
   (CANFIGGER_VERSION_MAJOR == (maj) && CANFIGGER_VERSION_MINOR >= (min)))

Compile-time version check.

Evaluates to a non-zero value if the canfigger headers are at least the given major and minor version. Useful for conditional compilation when a feature was added in a known release:

#if CANFIGGER_CHECK_VERSION(0, 4)
  // use API added in 0.4
#endif

Parameters

maj	Required major version.
min	Required minor version.

Definition at line 86 of file canfigger.h.

Enumeration Type Documentation

canfigger_user_dir

enum canfigger_user_dir

The well-known user directories, as named by the XDG user directories specification.

Passed to canfigger_user_dir(). These are the visible directories in a user's home - where a program should put a screenshot, an export or a downloaded file - and are unrelated to the base directories the rest of this API deals with.

Since

0.3.3

Definition at line 422 of file canfigger.h.

Function Documentation

canfigger_cache_dir()

char * canfigger_cache_dir

(

const char *

appname

)

Return the platform cache directory for an application.

On Unix, honours $XDG_CACHE_HOME if set; otherwise uses $HOME/.cache/appname. On Windows, uses LOCALAPPDATA%\appname\Cache - Windows has no cache root separate from its data root, so without the subdirectory this would return the same path as canfigger_data_dir().

The returned string is heap-allocated; the caller must free it.

Parameters

appname

Application name appended as a subdirectory.

Returns

Malloc'd path string, or NULL on failure or if appname is NULL/empty.

Since

0.3.2

Definition at line 658 of file canfigger.c.

canfigger_config_dir()

char * canfigger_config_dir

(

const char *

appname

)

Return the platform config directory for an application.

On Unix, honours $XDG_CONFIG_HOME if set; otherwise uses $HOME/.config/appname. On Windows, uses APPDATA%\appname.

The returned string is heap-allocated; the caller must free it.

Parameters

appname

Application name appended as a subdirectory.

Returns

Malloc'd path string, or NULL on failure or if appname is NULL/empty.

  char *dir = canfigger_config_dir("myapp");
  if (dir)
  {
    char *path = canfigger_path_join(dir, "settings.conf");
    free(dir);
    if (path)
    {
      struct Canfigger *list = canfigger_parse_file(path, ',');
      free(path);
      canfigger_free_list(&list);
    }
  }

Definition at line 608 of file canfigger.c.

canfigger_config_dirs()

char ** canfigger_config_dirs

(

void

)

Return the system config search path, most important first.

The directories in $XDG_CONFIG_DIRS, defaulting to /etc/xdg when it is unset or empty. These are searched after canfigger_config_dir(), which always takes precedence. Entries that are relative or empty are skipped, as the specification requires.

On Windows the list holds the single entry ProgramData%, the system-wide location for settings shared by every user.

Returns

Malloc'd NULL-terminated array of malloc'd strings, to be released with canfigger_free_dirs(), or NULL on allocation failure.

Since

0.3.3

Definition at line 799 of file canfigger.c.

canfigger_config_file()

char * canfigger_config_file

(

const char *

filename

)

Return the path to a config file in the platform base config directory.

Joins the base config directory with filename, without inserting an application-name subdirectory. On Unix, honours $XDG_CONFIG_HOME if set; otherwise uses $HOME/.config/filename. On Windows, uses APPDATA%\filename.

Use this when the config file lives directly under the config root rather than in a per-application subdirectory (e.g. $HOME/.config/apprc rather than $HOME/.config/app/apprc).

The returned string is heap-allocated; the caller must free it.

Parameters

filename

Config file name (or relative sub-path) to append.

Returns

Malloc'd path string, or NULL on failure or if filename is NULL or empty.

Since

0.3.2

  char *path = canfigger_config_file("apprc");
  if (path)
  {
    struct Canfigger *list = canfigger_parse_file(path, ',');
    free(path);
    canfigger_free_list(&list);
  }

Definition at line 619 of file canfigger.c.

canfigger_data_dir()

char * canfigger_data_dir

(

const char *

appname

)

Return the platform data directory for an application.

Intended for user-generated data (saves, state, cache) — not bundled application assets. On Unix, honours $XDG_DATA_HOME if set; otherwise uses $HOME/.local/share/appname. On Windows, uses LOCALAPPDATA%\appname.

The returned string is heap-allocated; the caller must free it.

Parameters

appname

Application name appended as a subdirectory.

Returns

Malloc'd path string, or NULL on failure or if appname is NULL/empty.

Definition at line 647 of file canfigger.c.

canfigger_data_dirs()

char ** canfigger_data_dirs

(

void

)

Return the system data search path, most important first.

The directories in $XDG_DATA_DIRS, defaulting to /usr/local/share:/usr/share when it is unset or empty. These are searched after canfigger_data_dir(), which always takes precedence. Entries that are relative or empty are skipped, as the specification requires.

On Windows the list holds the single entry ProgramData%, the system-wide location for data shared by every user.

Returns

Malloc'd NULL-terminated array of malloc'd strings, to be released with canfigger_free_dirs(), or NULL on allocation failure.

Since

0.3.3

Definition at line 810 of file canfigger.c.

canfigger_find_config_file()

char * canfigger_find_config_file	(	const char *	appname,
		const char *	filename
	)

Find an existing config file along the full config search path.

Returns the first readable file found, checking the user's own config directory first and then each entry of canfigger_config_dirs() in order, so a per-user file always overrides a system-wide one. This is the search the base directory specification describes.

With appname given, the paths checked are <config-dir>/appname/filename; with appname NULL or empty they are <config-dir>/filename, matching canfigger_config_file() for programs that keep a single file directly under the config root.

Only existing regular files match - a directory of the same name does not stop the search. The result is a path, not an open file: it may still fail to open, and it may be gone by the time it is used.

The returned string is heap-allocated; the caller must free it.

Parameters

appname	Application subdirectory to look in, or NULL for none.
filename	Config file name to look for.

Returns

Malloc'd path to the first matching file, or NULL if none exists or filename is NULL/empty.

Since

0.3.3

  /* The user's own myapp/myapp.conf wins; failing that, the first one found
     under $XDG_CONFIG_DIRS. NULL means neither exists. */
  char *path = canfigger_find_config_file("myapp", "myapp.conf");
  if (path)
  {
    struct Canfigger *list = canfigger_parse_file(path, ',');
    free(path);
    canfigger_free_list(&list);
  }

Definition at line 882 of file canfigger.c.

canfigger_free_current_attr_str_advance()

void canfigger_free_current_attr_str_advance	(	struct attributes *	attributes,
		char **	attr
	)

Free the current attribute string and advance to the next attribute.

On the first call for a given node, *attr must be NULL; the function loads the first attribute into *attr. On each subsequent call it frees the previous attribute string and loads the next. Sets *attr to NULL when no more attributes remain, or if attributes is NULL.

Typical usage:

char *attr = NULL;
canfigger_free_current_attr_str_advance(node->attributes, &attr);
while (attr) {
  // use attr
  canfigger_free_current_attr_str_advance(node->attributes, &attr);
}

Parameters

attributes	Pointer to the attributes structure of the current node (may be NULL, in which case *attr is set to NULL).
attr	Output parameter; set to the next attribute string on success, or NULL when the list is exhausted.

Definition at line 98 of file canfigger.c.

canfigger_free_current_key_node_advance()

void canfigger_free_current_key_node_advance

(

struct Canfigger **

node

)

Free the current node and advance the list pointer to the next node.

Releases all memory owned by *node (key, value, and any attributes), then sets *node to the next node in the list. Call this at the end of each loop iteration when walking the list:

while (list)
  canfigger_free_current_key_node_advance(&list);

Parameters

node	Double pointer to the current node; updated to point to the next node (or NULL at end of list) before returning.

Definition at line 137 of file canfigger.c.

canfigger_free_dirs()

void canfigger_free_dirs

(

char **

dirs

)

Free an array returned by canfigger_config_dirs() or canfigger_data_dirs().

Frees each string and then the array itself. Passing NULL is a no-op.

Parameters

dirs	Array to free.

Since

0.3.3

Definition at line 821 of file canfigger.c.

canfigger_free_list()

void canfigger_free_list

(

struct Canfigger **

node

)

Free all remaining nodes in the list.

Equivalent to calling canfigger_free_current_key_node_advance() in a loop until the list is empty. Use this for early-exit cleanup when you need to discard a partially-iterated list.

Parameters

node	Double pointer to the current (or head) node; set to NULL on return.

Definition at line 178 of file canfigger.c.

canfigger_parse_file()

struct Canfigger * canfigger_parse_file	(	const char *	file,
		const int	delimiter
	)

Parse a configuration file into a linked list of key-value nodes.

Reads file, strips a leading UTF-8 BOM if present, and returns a singly-linked list where each node holds one key-value entry. Lines beginning with # or [ and blank lines are ignored.

The delimiter character separates the value from the first attribute and each subsequent attribute from the next. Pass a character that does not appear in your values if you do not use attributes (e.g. ',').

The caller owns the returned list and must free it with canfigger_free_current_key_node_advance() (while iterating) or canfigger_free_list() (to discard the whole list at once).

Parameters

file	Path to the configuration file.
delimiter	Character that separates the value from attributes on a line.

Returns

Head of the linked list, or NULL if the file cannot be opened, is empty, or a memory allocation failure occurs.

Definition at line 368 of file canfigger.c.

canfigger_path_join()

char * canfigger_path_join	(	const char *	dir,
		const char *	file
	)

Join a directory path and a filename with the platform separator.

A separator is inserted between dir and file unless dir already ends with / or \.

The returned string is heap-allocated; the caller must free it.

Parameters

dir	Directory portion of the path.
file	Filename (or relative sub-path) to append.

Returns

Malloc'd joined path string, or NULL if either argument is NULL or empty, or on allocation failure.

  char *path =
    canfigger_path_join("/home/user/.config/myapp", "settings.conf");
  if (path)
  {
    struct Canfigger *list = canfigger_parse_file(path, ',');
    free(path);
    canfigger_free_list(&list);
  }

Definition at line 834 of file canfigger.c.

canfigger_runtime_dir()

char * canfigger_runtime_dir

(

const char *

appname

)

Return the runtime directory for an application, or NULL.

For short-lived per-session files: sockets, lock and PID files, and secrets that should not outlive the login session.

On Unix this is $XDG_RUNTIME_DIR. Unlike the other directory helpers there is deliberately no $HOME fallback, because the specification attaches requirements to this directory that an arbitrary fallback would not meet: it must exist, be owned by the calling user, and have mode 0700. Those conditions are checked, and NULL is returned if any of them fails or the variable is unset - a common case in cron, container and other sessions that never set one.

On Windows there is no equivalent concept and NULL is always returned. A path under LOCALAPPDATA% would persist across sessions, so returning one would misrepresent what the caller asked for.

A NULL return is therefore an ordinary outcome, not an error: choose a fallback appropriate to the data, such as canfigger_cache_dir() for anything that can be regenerated or safely lost.

The returned string is heap-allocated; the caller must free it.

Parameters

appname

Application name appended as a subdirectory.

Returns

Malloc'd path string, or NULL if no usable runtime directory exists or appname is NULL/empty.

Since

0.3.3

Definition at line 680 of file canfigger.c.

canfigger_state_dir()

char * canfigger_state_dir

(

const char *

appname

)

Return the platform state directory for an application.

For data that should persist between runs but is not configuration and is not worth backing up - logs, history, recently-used lists, and similar. On Unix, honours $XDG_STATE_HOME if set; otherwise uses $HOME/.local/state/appname. On Windows, uses LOCALAPPDATA%\appname\State, for the same collision reason described under canfigger_cache_dir().

The returned string is heap-allocated; the caller must free it.

Parameters

appname

Application name appended as a subdirectory.

Returns

Malloc'd path string, or NULL on failure or if appname is NULL/empty.

Since

0.3.3

Definition at line 669 of file canfigger.c.

canfigger_user_dir()

char * canfigger_user_dir

(

enum canfigger_user_dir

which

)

Return one of the user's well-known directories.

On Unix the answer comes from user-dirs.dirs in the config directory, which the desktop session writes and localises - so the desktop directory is ~/Desktop on an English system and ~/Skrivebord on a Danish one. Never assume the English name. That file is a shell fragment, not a canfigger file, so it is parsed separately: values are double-quoted, a leading $HOME/ is expanded, and entries that are neither absolute nor under $HOME are ignored.

When the file is missing or the entry is unset - a headless, container or minimal-desktop session, where nothing writes it - the result is $HOME, except for CANFIGGER_USER_DIR_DESKTOP which keeps its historical $HOME/Desktop default. This mirrors the reference xdg-user-dir tool.

On Windows the equivalent shell folder is returned (Desktop, Documents, Music, Pictures, Videos, Templates, and the public documents folder for CANFIGGER_USER_DIR_PUBLICSHARE).

The directory is not created and is not guaranteed to exist.

The returned string is heap-allocated; the caller must free it.

Parameters

which

Which directory to return.

Returns

Malloc'd path string, or NULL if which is out of range, $HOME is unset, or allocation fails.

Since

0.3.3

Definition at line 1064 of file canfigger.c.