include/basedir.h

   1 /** @file basedir.h
   2   * @brief Functions for using the XDG basedir specification.
   3   * See http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html for details. */
   4
   5 #ifndef XDG_BASEDIR_H
   6 #define XDG_BASEDIR_H
   7
   8 #include <stdbool.h>
   9 #include <stdio.h>
  10
  11 #ifdef __cplusplus
  12 extern "C" {
  13 #endif
  14
  15 /** Version of XDG basedir-spec implemented in this library. */
  16 #define XDG_BASEDIR_SPEC 0.6
  17
  18 /** @name XDG data cache management */
  19 /*@{*/
  20
  21 /** @struct xdgHandle
  22   * Handle to XDG data cache.
  23   * Handles are allocated with xdgAllocHandle() and
  24   * freed with xdgFreeHandle(). */
  25 typedef struct _xdgHandle {
  26         void *reserved;
  27 } *xdgHandle;
  28
  29 /** Get a handle to an XDG data cache and initialize the cache.
  30   * Use xdgFreeHandle() to free the handle. */
  31 xdgHandle xdgAllocHandle();
  32
  33 /** Free handle to XDG data cache.
  34   * Free handle allocated using xdgAllocHandle(). */
  35 void xdgFreeHandle(xdgHandle handle);
  36
  37 /** Update the data cache.
  38   * This should not be done frequently as it reallocates the cache.
  39   * Even if updating the cache fails the handle remains valid and can
  40   * be used to access XDG data as it was before xdgUpdateData() was called.
  41   * @return 0 if update failed, non-0 if successful.*/
  42 bool xdgUpdateData(xdgHandle handle);
  43
  44 /*@}*/
  45 /** @name Basic XDG-Basedir Queries */
  46 /*@{*/
  47
  48 /** Base directory for user specific data files.
  49   * "${XDG_DATA_HOME:-$HOME/.local/share}" */
  50 const char * xdgDataHome(xdgHandle handle);
  51
  52 /** Base directory for user specific configuration files.
  53   * "${XDG_CONFIG_HOME:-$HOME/.config}" */
  54 const char * xdgConfigHome(xdgHandle handle);
  55
  56 /** Preference-ordered set of base directories to search for data files
  57   * in addition to the $XDG_DATA_HOME base directory.
  58   * "${XDG_DATA_DIRS:-/usr/local/share/:/usr/share/}".
  59   * @return A null-terminated list of directory strings. */
  60 const char * const * xdgDataDirectories(xdgHandle handle);
  61
  62 /** Preference-ordered set of base directories to search for data files
  63   * with $XDG_DATA_HOME prepended.
  64   * The base directory defined by $XDG_DATA_HOME is considered more
  65   * important than any of the base directories defined by $XDG_DATA_DIRS.
  66   * @return A null-terminated list of directory strings. */
  67 const char * const * xdgSearchableDataDirectories(xdgHandle handle);
  68
  69 /** Preference-ordered set of base directories to search for configuration
  70   * files in addition to the $XDG_CONFIG_HOME base directory.
  71   * "${XDG_CONFIG_DIRS:-/etc/xdg}".
  72   * @return A null-terminated list of directory strings. */
  73 const char * const * xdgConfigDirectories(xdgHandle handle);
  74
  75 /** Preference-ordered set of base directories to search for configuration
  76   * files with $XDG_CONFIG_HOME prepended.
  77   * The base directory defined by $XDG_CONFIG_HOME is considered more
  78   * important than any of the base directories defined by $XDG_CONFIG_DIRS.
  79   * @return A null-terminated list of directory strings. */
  80 const char * const * xdgSearchableConfigDirectories(xdgHandle handle);
  81
  82 /** Base directory for user specific non-essential data files.
  83   * "${XDG_CACHE_HOME:-$HOME/.cache}" */
  84 const char * xdgCacheHome(xdgHandle handle);
  85
  86 /*@}*/
  87
  88 /** @name Higher-level XDG-Basedir Queries */
  89 /*@{*/
  90
  91 /** Find all existing data files corresponding to relativePath.
  92  *      Consider as performing @code fopen(filename, "r") @endcode on every possible @c filename
  93  *              and returning the successful <tt>filename</tt>s.
  94  *      @param relativePath Path to scan for.
  95  *      @param handle Handle to data cache.
  96  *      @return A sequence of null-terminated strings terminated by a double-null (empty string)
  97  *              and allocated using malloc().
  98  */
  99 const char * xdgDataFind(const char* relativePath, xdgHandle handle);
 100
 101 /** Find all existing config files corresponding to relativePath.
 102   * Consider as performing @code fopen(filename, "r") @endcode on every possible @c filename
 103   *     and returning the successful <tt>filename</tt>s.
 104   * @param relativePath Path to scan for.
 105   * @param handle Handle to data cache.
 106   * @return A sequence of null-terminated strings terminated by a double-null (empty string)
 107   *     and allocated using malloc().
 108   */
 109 const char * xdgConfigFind(const char* relativePath, xdgHandle handle);
 110
 111 /** Open first possible data file corresponding to relativePath.
 112   * Consider as performing @code fopen(filename, mode) @endcode on every possible @c filename
 113   *     and returning the first successful @c filename or @c NULL.
 114   * @param relativePath Path to scan for.
 115   * @param mode Mode with which to attempt to open files (see fopen modes).
 116   * @param handle Handle to data cache.
 117   * @return File pointer if successful else @c NULL. Client must use @c fclose to close file.
 118   */
 119 FILE * xdgDataOpen(const char* relativePath, const char* mode, xdgHandle handle);
 120
 121 /** Open first possible config file corresponding to relativePath.
 122   * Consider as performing @code fopen(filename, mode) @endcode on every possible @c filename
 123   *     and returning the first successful @c filename or @c NULL.
 124   * @param relativePath Path to scan for.
 125   * @param mode Mode with which to attempt to open files (see fopen modes).
 126   * @param handle Handle to data cache.
 127   * @return File pointer if successful else @c NULL. Client must use @c fclose to close file.
 128   */
 129 FILE * xdgConfigOpen(const char* relativePath, const char* mode, xdgHandle handle);
 130
 131 /*@}*/
 132
 133 #ifdef __cplusplus
 134 } // extern "C"
 135 #endif
 136
 137 #endif /*XDG_BASEDIR_H*/