libxdg-basedir-1.2.0 1.2.0
basedir.c File Reference

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

#include <config.h>
#include <stdlib.h>
#include <memory.h>
#include <string.h>
#include <errno.h>
#include <sys/stat.h>
#include <basedir.h>
#include <basedir_fs.h>
Include dependency graph for basedir.c:

Go to the source code of this file.

Functions

static xdgCachedData * xdgGetCache (xdgHandle *handle)
 Get cache object associated with a handle.
 
xdgHandlexdgInitHandle (xdgHandle *handle)
 Initialize a handle to an XDG data cache and initialize the cache.
 
static void xdgFreeStringList (char **list)
 Free all memory used by a NULL-terminated string list.
 
static void xdgFreeData (xdgCachedData *cache)
 Free all data in the cache and set pointers to null.
 
void xdgWipeHandle (xdgHandle *handle)
 Wipe handle of XDG data cache.
 
static char ** xdgSplitPath (const char *string)
 Split string at ':', return null-terminated list of resulting strings.
 
static char ** xdgGetPathListEnv (const char *name, const char **defaults)
 Get $PATH-style environment variable as list of strings.
 
static char * xdgGetEnv (const char *name)
 Get value of an environment variable.
 
static char * xdgEnvDup (const char *name)
 Duplicate an environment variable.
 
static int xdgUpdateHomeDirectories (xdgCachedData *cache)
 Update all *Home variables of cache.
 
static char ** xdgGetDirectoryLists (const char *envname, char *homedir, const char **defaults)
 Get directory lists with initial home directory.
 
static int xdgUpdateDirectoryLists (xdgCachedData *cache)
 Update all *Directories variables of cache.
 
int xdgUpdateData (xdgHandle *handle)
 Update the data cache.
 
static char * xdgFindExisting (const char *relativePath, const char *const *dirList)
 Find all existing files corresponding to relativePath relative to each item in dirList.
 
static FILE * xdgFileOpen (const char *relativePath, const char *mode, const char *const *dirList)
 Open first possible config file corresponding to relativePath.
 
int xdgMakePath (const char *path, mode_t mode)
 Create path by recursively creating directories.
 
static char * xdgGetRelativeHome (const char *envname, const char *relativefallback, unsigned int fallbacklength)
 Get a home directory from the environment or a fallback relative to $HOME.
 
const char * xdgDataHome (xdgHandle *handle)
 Base directory for user specific data files.
 
const char * xdgConfigHome (xdgHandle *handle)
 Base directory for user specific configuration files.
 
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.
 
const char *const * xdgSearchableDataDirectories (xdgHandle *handle)
 Preference-ordered set of base directories to search for data files with $XDG_DATA_HOME prepended.
 
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.
 
const char *const * xdgSearchableConfigDirectories (xdgHandle *handle)
 Preference-ordered set of base directories to search for configuration files with $XDG_CONFIG_HOME prepended.
 
const char * xdgCacheHome (xdgHandle *handle)
 Base directory for user specific non-essential data files.
 
const char * xdgRuntimeDirectory (xdgHandle *handle)
 Base directory for user specific non-essential runtime files such as sockets and named pipes.
 
char * xdgDataFind (const char *relativePath, xdgHandle *handle)
 Find all existing data files corresponding to relativePath.
 
char * xdgConfigFind (const char *relativePath, xdgHandle *handle)
 Find all existing config files corresponding to relativePath.
 
FILE * xdgDataOpen (const char *relativePath, const char *mode, xdgHandle *handle)
 Open first possible data file corresponding to relativePath.
 
FILE * xdgConfigOpen (const char *relativePath, const char *mode, xdgHandle *handle)
 Open first possible config file corresponding to relativePath.
 

Detailed Description

Implementation of the XDG Base Directory specification.

Definition in file basedir.c.

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.

Definition at line 643 of file basedir.c.

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

Definition at line 623 of file basedir.c.

◆ 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"

Definition at line 664 of file basedir.c.

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

Definition at line 596 of file basedir.c.

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

Definition at line 678 of file basedir.c.

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

Definition at line 603 of file basedir.c.

◆ 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"

Definition at line 657 of file basedir.c.

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

Definition at line 589 of file basedir.c.

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

Definition at line 671 of file basedir.c.

◆ xdgEnvDup()

static char * xdgEnvDup ( const char * name)
static

Duplicate an environment variable.

Sets errno to ENOMEM if unable to allocate duplicate string. Sets errno to EINVAL if variable is not set or empty.

Returns
The duplicated string or NULL if an error occurs.

Definition at line 295 of file basedir.c.

◆ xdgFileOpen()

static FILE * xdgFileOpen ( const char * relativePath,
const char * mode,
const char *const * dirList )
static

Open first possible config file corresponding to relativePath.

Parameters
relativePathPath to scan for.
modeMode with which to attempt to open files (see fopen modes).
dirListNULL-terminated list of paths in which to search for relativePath.
Returns
File pointer if successful else NULL. Client must use fclose to close file.

Definition at line 501 of file basedir.c.

◆ xdgFindExisting()

static char * xdgFindExisting ( const char * relativePath,
const char *const * dirList )
static

Find all existing files corresponding to relativePath relative to each item in dirList.

Parameters
relativePathRelative path to search for.
dirListNULL-terminated list of directory paths.
Returns
A sequence of null-terminated strings terminated by a double-NULL (empty string) and allocated using malloc().

Definition at line 449 of file basedir.c.

◆ xdgGetDirectoryLists()

static char ** xdgGetDirectoryLists ( const char * envname,
char * homedir,
const char ** defaults )
static

Get directory lists with initial home directory.

Parameters
envnameEnvironment variable with colon-seperated directories.
homedirHome directory for this directory list or NULL. This parameter should be allocated on the heap. The returned list will start with this path, and should be considered as owning the memory.
defaultsDefault directories if environment variable is not set.
Returns
An array of strings. Both the array and its contents are allocated with malloc(). The function xdgFreeStringList is provided for conveniantly free()-ing the list and all its elements.

Definition at line 373 of file basedir.c.

◆ xdgGetEnv()

static char * xdgGetEnv ( const char * name)
static

Get value of an environment variable.

Sets errno to EINVAL if variable is not set or empty.

Parameters
nameName of environment variable.
Returns
The environment variable or NULL if an error occurs.

Definition at line 280 of file basedir.c.

◆ xdgGetPathListEnv()

static char ** xdgGetPathListEnv ( const char * name,
const char ** defaults )
static

Get $PATH-style environment variable as list of strings.

If $name is unset or empty, use default strings specified by variable arguments.

Parameters
nameName of environment variable
defaultsNULL-terminated list of strings to be copied and used as defaults

Definition at line 240 of file basedir.c.

◆ xdgGetRelativeHome()

static char * xdgGetRelativeHome ( const char * envname,
const char * relativefallback,
unsigned int fallbacklength )
static

Get a home directory from the environment or a fallback relative to $HOME.

Sets errno to ENOMEM if unable to allocate duplicate string. Sets errno to EINVAL if variable is not set or empty.

Parameters
envnameName of environment variable.
relativefallbackPath starting with "/" and relative to $HOME to use as fallback.
fallbacklengthstrlen(relativefallback).
Returns
The home directory path or NULL of an error occurs.

Definition at line 572 of file basedir.c.

◆ 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

Definition at line 123 of file basedir.c.

◆ 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)

Definition at line 523 of file basedir.c.

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

Definition at line 650 of file basedir.c.

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

Definition at line 630 of file basedir.c.

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

Definition at line 610 of file basedir.c.

◆ xdgSplitPath()

static char ** xdgSplitPath ( const char * string)
static

Split string at ':', return null-terminated list of resulting strings.

Parameters
stringString to be split

Definition at line 180 of file basedir.c.

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

Definition at line 414 of file basedir.c.

◆ xdgUpdateDirectoryLists()

static int xdgUpdateDirectoryLists ( xdgCachedData * cache)
static

Update all *Directories variables of cache.

This includes xdgCachedData::searchableDataDirectories and xdgCachedData::searchableConfigDirectories.

Parameters
cacheData cache to be updated.

Definition at line 402 of file basedir.c.

◆ xdgUpdateHomeDirectories()

static int xdgUpdateHomeDirectories ( xdgCachedData * cache)
static

Update all *Home variables of cache.

This includes xdgCachedData::dataHome, xdgCachedData::configHome and xdgCachedData::cacheHome.

Parameters
cacheData cache to be updated

Definition at line 308 of file basedir.c.

◆ xdgWipeHandle()

void xdgWipeHandle ( xdgHandle * handle)

Wipe handle of XDG data cache.

Wipe handle initialized using xdgInitHandle().

Definition at line 170 of file basedir.c.