include/basedir.h

   1 /* Copyright (c) 2007 Mark Nevill
   2  *
   3  * Permission is hereby granted, free of charge, to any person
   4  * obtaining a copy of this software and associated documentation
   5  * files (the "Software"), to deal in the Software without
   6  * restriction, including without limitation the rights to use,
   7  * copy, modify, merge, publish, distribute, sublicense, and/or sell
   8  * copies of the Software, and to permit persons to whom the
   9  * Software is furnished to do so, subject to the following
  10  * conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be
  13  * included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  17  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  19  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  20  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  22  * OTHER DEALINGS IN THE SOFTWARE.
  23  */
  24
  25 /** @file basedir.h
  26   * @brief Functions for using the XDG Base Directory specification.
  27   * See http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html for details. */
  28
  29 #ifndef XDG_BASEDIR_H
  30 #define XDG_BASEDIR_H
  31
  32 #if !defined(__cplusplus) && !defined(__bool_true_false_are_defined)
  33 #if STDC_HEADERS || HAVE_STDBOOL_H || defined(_DOXYGEN)
  34 #include <stdbool.h>
  35 #else
  36 #if HAVE__BOOL
  37 #define bool _Bool
  38 #else
  39 #define bool int
  40 #endif // HAVE__BOOL
  41 #define true 1
  42 #define false 0
  43 #define XDG_BASEDIR_H_LOCAL_BOOL_DEFINE
  44 #define __bool_true_false_are_defined
  45 #endif // STDC_HEADERS || HAVE_STDBOOL_H || _DOXYGEN
  46 #endif // !__cplusplus && !__bool_true_false_are_defined
  47
  48 #include <stdio.h>
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 /** Version of XDG Base Directory specification implemented in this library. */
  55 #define XDG_BASEDIR_SPEC 0.6
  56
  57 /** @name XDG data cache management */
  58 /*@{*/
  59
  60 /** Handle to XDG data cache.
  61   * Handles are allocated with xdgAllocHandle() and
  62   * freed with xdgFreeHandle(). */
  63 typedef struct /*_xdgHandle*/ {
  64         /** Reserved for internal use, do not modify. */
  65         void *reserved;
  66 } *xdgHandle;
  67
  68 /** Get a handle to an XDG data cache and initialize the cache.
  69   * Use xdgFreeHandle() to free the handle.
  70   * @return a handle if allocation was successful, else 0 */
  71 xdgHandle xdgAllocHandle();
  72
  73 /** Free handle to XDG data cache.
  74   * Free handle allocated using xdgAllocHandle(). */
  75 void xdgFreeHandle(xdgHandle handle);
  76
  77 /** Update the data cache.
  78   * This should not be done frequently as it reallocates the cache.
  79   * Even if updating the cache fails the handle remains valid and can
  80   * be used to access XDG data as it was before xdgUpdateData() was called.
  81   * @return 0 if update failed, non-0 if successful.*/
  82 bool xdgUpdateData(xdgHandle handle);
  83
  84 /*@}*/
  85 /** @name Basic XDG Base Directory Queries */
  86 /*@{*/
  87
  88 /** Base directory for user specific data files.
  89   * @param handle Handle to data cache, allocated with xdgAllocHandle().
  90   * @return a path as described by the standards. */
  91 const char * xdgDataHome(xdgHandle handle);
  92
  93 /** Base directory for user specific configuration files.
  94   * @param handle Handle to data cache, allocated with xdgAllocHandle().
  95   * @return a path as described by the standards. */
  96 const char * xdgConfigHome(xdgHandle handle);
  97
  98 /** Preference-ordered set of base directories to search for data files
  99   * in addition to the $XDG_DATA_HOME base directory.
 100   * @param handle Handle to data cache, allocated with xdgAllocHandle().
 101   * @return A null-terminated list of directory strings. */
 102 const char * const * xdgDataDirectories(xdgHandle handle);
 103
 104 /** Preference-ordered set of base directories to search for data files
 105   * with $XDG_DATA_HOME prepended.
 106   * The base directory defined by $XDG_DATA_HOME is considered more
 107   * important than any of the base directories defined by $XDG_DATA_DIRS.
 108   * @param handle Handle to data cache, allocated with xdgAllocHandle().
 109   * @return A null-terminated list of directory strings. */
 110 const char * const * xdgSearchableDataDirectories(xdgHandle handle);
 111
 112 /** Preference-ordered set of base directories to search for configuration
 113   * files in addition to the $XDG_CONFIG_HOME base directory.
 114   * @param handle Handle to data cache, allocated with xdgAllocHandle().
 115   * @return A null-terminated list of directory strings. */
 116 const char * const * xdgConfigDirectories(xdgHandle handle);
 117
 118 /** Preference-ordered set of base directories to search for configuration
 119   * files with $XDG_CONFIG_HOME prepended.
 120   * The base directory defined by $XDG_CONFIG_HOME is considered more
 121   * important than any of the base directories defined by $XDG_CONFIG_DIRS.
 122   * @param handle Handle to data cache, allocated with xdgAllocHandle().
 123   * @return A null-terminated list of directory strings. */
 124 const char * const * xdgSearchableConfigDirectories(xdgHandle handle);
 125
 126 /** Base directory for user specific non-essential data files.
 127   * @param handle Handle to data cache, allocated with xdgAllocHandle().
 128   * @return a path as described by the standards. */
 129 const char * xdgCacheHome(xdgHandle handle);
 130
 131 /*@}*/
 132
 133 /** @name Higher-level XDG Base Directory Queries */
 134 /*@{*/
 135
 136 /** Find all existing data files corresponding to relativePath.
 137   * Consider as performing @code fopen(filename, "r") @endcode on every possible @c filename
 138   *     and returning the successful <tt>filename</tt>s.
 139   * @param relativePath Path to scan for.
 140   * @param handle Handle to data cache, allocated with xdgAllocHandle().
 141   * @return A sequence of null-terminated strings terminated by a double-null (empty string)
 142   *     and allocated using malloc(), e.g.: @code "/etc/share\0/home/jdoe/.local\0" @endcode
 143   */
 144 const char * xdgDataFind(const char* relativePath, xdgHandle handle);
 145
 146 /** Find all existing config files corresponding to relativePath.
 147   * Consider as performing @code fopen(filename, "r") @endcode on every possible @c filename
 148   *     and returning the successful <tt>filename</tt>s.
 149   * @param relativePath Path to scan for.
 150   * @param handle Handle to data cache, allocated with xdgAllocHandle().
 151   * @return A sequence of null-terminated strings terminated by a double-null (empty string)
 152   *     and allocated using malloc(), e.g.: @code "/etc/xdg\0/home/jdoe/.config\0" @endcode
 153   */
 154 const char * xdgConfigFind(const char* relativePath, xdgHandle handle);
 155
 156 /** Open first possible data file corresponding to relativePath.
 157   * Consider as performing @code fopen(filename, mode) @endcode on every possible @c filename
 158   *     and returning the first successful @c filename or @c NULL.
 159   * @param relativePath Path to scan for.
 160   * @param mode Mode with which to attempt to open files (see fopen modes).
 161   * @param handle Handle to data cache, allocated with xdgAllocHandle().
 162   * @return File pointer if successful else @c NULL. Client must use @c fclose to close file.
 163   */
 164 FILE * xdgDataOpen(const char* relativePath, const char* mode, xdgHandle handle);
 165
 166 /** Open first possible config file corresponding to relativePath.
 167   * Consider as performing @code fopen(filename, mode) @endcode on every possible @c filename
 168   *     and returning the first successful @c filename or @c NULL.
 169   * @param relativePath Path to scan for.
 170   * @param mode Mode with which to attempt to open files (see fopen modes).
 171   * @param handle Handle to data cache, allocated with xdgAllocHandle().
 172   * @return File pointer if successful else @c NULL. Client must use @c fclose to close file.
 173   */
 174 FILE * xdgConfigOpen(const char* relativePath, const char* mode, xdgHandle handle);
 175
 176 /*@}*/
 177
 178 #ifdef __cplusplus
 179 } // extern "C"
 180 #endif
 181
 182 #ifdef XDG_BASEDIR_H_LOCAL_BOOL_DEFINE
 183 #undef bool
 184 #undef true
 185 #undef false
 186 #undef __bool_true_false_are_defined
 187 #undef XDG_BASEDIR_H_LOCAL_BOOL_DEFINE
 188 #endif
 189
 190 #endif /*XDG_BASEDIR_H*/