XDG Base Directory Specifications Library 1.1.1
Classes | Macros | Typedefs | Functions
basedir.c File Reference

Implementation of the XDG Base Directory specification. More...

#include <stdlib.h>
#include <memory.h>
#include <string.h>
#include <errno.h>
#include <sys/stat.h>
#include <basedir.h>
#include <basedir_fs.h>

Classes

struct  _xdgCachedData
 

Macros

#define FALSE   0
 
#define TRUE   1
 
#define xdgZeroMemory(p, n)   memset(p, 0, n)
 
#define DIR_SEPARATOR_CHAR   '/'
 
#define DIR_SEPARATOR_STR   "/"
 
#define PATH_SEPARATOR_CHAR   ':'
 
#define PATH_SEPARATOR_STR   ":"
 
#define NO_ESCAPES_IN_PATHS
 
#define MAX(a, b)   ((b) > (a) ? (b) : (a))
 

Typedefs

typedef struct _xdgCachedData xdgCachedData
 

Functions

xdgHandlexdgInitHandle (xdgHandle *handle)
 
void xdgWipeHandle (xdgHandle *handle)
 
int xdgUpdateData (xdgHandle *handle)
 
int xdgMakePath (const char *path, mode_t mode)
 
const char * xdgDataHome (xdgHandle *handle)
 
const char * xdgConfigHome (xdgHandle *handle)
 
const char *const * xdgDataDirectories (xdgHandle *handle)
 
const char *const * xdgSearchableDataDirectories (xdgHandle *handle)
 
const char *const * xdgConfigDirectories (xdgHandle *handle)
 
const char *const * xdgSearchableConfigDirectories (xdgHandle *handle)
 
const char * xdgCacheHome (xdgHandle *handle)
 
const char * xdgRuntimeDirectory (xdgHandle *handle)
 
char * xdgDataFind (const char *relativePath, xdgHandle *handle)
 
char * xdgConfigFind (const char *relativePath, xdgHandle *handle)
 
FILE * xdgDataOpen (const char *relativePath, const char *mode, xdgHandle *handle)
 
FILE * xdgConfigOpen (const char *relativePath, const char *mode, xdgHandle *handle)
 

Detailed Description

Implementation of the XDG Base Directory specification.

Function Documentation

◆ xdgCacheHome()

const char * xdgCacheHome ( xdgHandle handle)

Base directory for user specific non-essential data files.

Parameters
handleHandle to data cache, initialized with xdgInitHandle().
Returns
a path as described by the standards.

◆ xdgConfigDirectories()

const char *const * xdgConfigDirectories ( xdgHandle handle)

Preference-ordered set of base directories to search for configuration files in addition to the $XDG_CONFIG_HOME base directory.

Parameters
handleHandle to data cache, initialized with xdgInitHandle().
Returns
A null-terminated list of directory strings.

◆ xdgConfigFind()

char * xdgConfigFind ( const char *  relativePath,
xdgHandle handle 
)

Find all existing config files corresponding to relativePath. Consider as performing

fopen(filename, "r")

on every possible filename and returning the successful filenames.

Parameters
relativePathPath to scan for.
handleHandle to data cache, initialized with xdgInitHandle().
Returns
A sequence of null-terminated strings terminated by a double-null (empty string) and allocated using malloc(), e.g.:
"/etc/xdg\0/home/jdoe/.config\0"

◆ xdgConfigHome()

const char * xdgConfigHome ( xdgHandle handle)

Base directory for user specific configuration files.

Parameters
handleHandle to data cache, initialized with xdgInitHandle().
Returns
a path as described by the standards.

◆ xdgConfigOpen()

FILE * xdgConfigOpen ( const char *  relativePath,
const char *  mode,
xdgHandle handle 
)

Open first possible config file corresponding to relativePath. Consider as performing

fopen(filename, mode)

on every possible filename and returning the first successful filename or NULL.

Parameters
relativePathPath to scan for.
modeMode with which to attempt to open files (see fopen modes).
handleHandle to data cache, initialized with xdgInitHandle().
Returns
File pointer if successful else NULL. Client must use fclose to close file.

◆ xdgDataDirectories()

const char *const * xdgDataDirectories ( xdgHandle handle)

Preference-ordered set of base directories to search for data files in addition to the $XDG_DATA_HOME base directory.

Parameters
handleHandle to data cache, initialized with xdgInitHandle().
Returns
A null-terminated list of directory strings.

◆ xdgDataFind()

char * xdgDataFind ( const char *  relativePath,
xdgHandle handle 
)

Find all existing data files corresponding to relativePath. Consider as performing

fopen(filename, "r")

on every possible filename and returning the successful filenames.

Parameters
relativePathPath to scan for.
handleHandle to data cache, initialized with xdgInitHandle().
Returns
A sequence of null-terminated strings terminated by a double-null (empty string) and allocated using malloc(), e.g.:
"/etc/share\0/home/jdoe/.local\0"

◆ xdgDataHome()

const char * xdgDataHome ( xdgHandle handle)

Base directory for user specific data files.

Parameters
handleHandle to data cache, initialized with xdgInitHandle().
Returns
a path as described by the standards.

◆ xdgDataOpen()

FILE * xdgDataOpen ( const char *  relativePath,
const char *  mode,
xdgHandle handle 
)

Open first possible data file corresponding to relativePath. Consider as performing

fopen(filename, mode)

on every possible filename and returning the first successful filename or NULL.

Parameters
relativePathPath to scan for.
modeMode with which to attempt to open files (see fopen modes).
handleHandle to data cache, initialized with xdgInitHandle().
Returns
File pointer if successful else NULL. Client must use fclose to close file.

◆ xdgInitHandle()

xdgHandle * xdgInitHandle ( xdgHandle handle)

Initialize a handle to an XDG data cache and initialize the cache. Use xdgWipeHandle() to free the handle.

Returns
a pointer to the handle if initialization was successful, else 0

◆ xdgMakePath()

int xdgMakePath ( const char *  path,
mode_t  mode 
)

Create path by recursively creating directories. This utility function is not part of the XDG specification, but nevertheless useful in context of directory manipulation.

Parameters
pathThe path to be created.
modeThe permissions to use for created directories. This parameter is modified by the process's umask. For details, see mkdir(2)'s mode parameter.
Returns
Zero on success, -1 if an error occured (in which case errno will be set appropriately)

◆ xdgRuntimeDirectory()

const char * xdgRuntimeDirectory ( xdgHandle handle)

Base directory for user specific non-essential runtime files such as sockets and named pipes.

Parameters
handleHandle to data cache, initialized with xdgInitHandle().
Returns
a path as described by the standards, or NULL if no path has been set.

◆ xdgSearchableConfigDirectories()

const char *const * xdgSearchableConfigDirectories ( xdgHandle handle)

Preference-ordered set of base directories to search for configuration files with $XDG_CONFIG_HOME prepended. The base directory defined by $XDG_CONFIG_HOME is considered more important than any of the base directories defined by $XDG_CONFIG_DIRS.

Parameters
handleHandle to data cache, initialized with xdgInitHandle().
Returns
A null-terminated list of directory strings.

◆ xdgSearchableDataDirectories()

const char *const * xdgSearchableDataDirectories ( xdgHandle handle)

Preference-ordered set of base directories to search for data files with $XDG_DATA_HOME prepended. The base directory defined by $XDG_DATA_HOME is considered more important than any of the base directories defined by $XDG_DATA_DIRS.

Parameters
handleHandle to data cache, initialized with xdgInitHandle().
Returns
A null-terminated list of directory strings.

◆ xdgUpdateData()

int xdgUpdateData ( xdgHandle handle)

Update the data cache. This should not be done frequently as it reallocates the cache. Even if updating the cache fails the handle remains valid and can be used to access XDG data as it was before xdgUpdateData() was called.

Returns
0 if update failed, non-0 if successful.

◆ xdgWipeHandle()

void xdgWipeHandle ( xdgHandle handle)

Wipe handle of XDG data cache. Wipe handle initialized using xdgInitHandle().