libxdg-basedir-1.1.1 1.1.1
Functions
src/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>

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

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 636 of file basedir.c.

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 616 of file basedir.c.

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 650 of file basedir.c.

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 589 of file basedir.c.

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 664 of file basedir.c.

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 596 of file basedir.c.

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 643 of file basedir.c.

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 582 of file basedir.c.

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 657 of file basedir.c.

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 293 of file basedir.c.

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 494 of file basedir.c.

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 442 of file basedir.c.

static void xdgFreeData ( xdgCachedData *  cache) [static]

Free all data in the cache and set pointers to null.

Definition at line 142 of file basedir.c.

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 366 of file basedir.c.

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 278 of file basedir.c.

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 238 of file basedir.c.

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 565 of file basedir.c.

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 122 of file basedir.c.

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 516 of file basedir.c.

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 623 of file basedir.c.

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 603 of file basedir.c.

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 178 of file basedir.c.

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 407 of file basedir.c.

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 395 of file basedir.c.

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 306 of file basedir.c.

void xdgWipeHandle ( xdgHandle handle)

Wipe handle of XDG data cache.

Wipe handle initialized using xdgInitHandle().

Definition at line 168 of file basedir.c.