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