summaryrefslogtreecommitdiff
path: root/legacy/efreet
diff options
context:
space:
mode:
authorGustavo Sverzut Barbieri <barbieri@gmail.com>2012-10-09 18:43:33 +0000
committerGustavo Sverzut Barbieri <barbieri@gmail.com>2012-10-09 18:43:33 +0000
commit4786babcc8466652e79ca926108449ee9b78aada (patch)
tree3bf85591f04baf63da31d0a65463d0b98c99dd30 /legacy/efreet
parent753f334e731f345ee4cc1202387bfc0ba61ece21 (diff)
Improve xdg-user-dirs documentation.
EVERYBODY writing software, particularly applications, read this documentation and the links below so you can make your software compliant: * http://0pointer.de/blog/projects/tmp.html where to store files and sockets to be secure and portable. * http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html SVN revision: 77669
Diffstat (limited to 'legacy/efreet')
-rw-r--r--legacy/efreet/src/lib/efreet_base.h138
1 files changed, 138 insertions, 0 deletions
diff --git a/legacy/efreet/src/lib/efreet_base.h b/legacy/efreet/src/lib/efreet_base.h
index d0de7e7569..1f8801816b 100644
--- a/legacy/efreet/src/lib/efreet_base.h
+++ b/legacy/efreet/src/lib/efreet_base.h
@@ -7,6 +7,9 @@
7 * @addtogroup Efreet_Base Efreet_Base: The XDG Base Directory Specification 7 * @addtogroup Efreet_Base Efreet_Base: The XDG Base Directory Specification
8 * functions 8 * functions
9 * 9 *
10 * @see http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
11 * @see http://0pointer.de/blog/projects/tmp.html
12 *
10 * @{ 13 * @{
11 */ 14 */
12 15
@@ -14,6 +17,9 @@
14/** 17/**
15 * @return Returns the XDG Data Home directory 18 * @return Returns the XDG Data Home directory
16 * @brief Retrieves the XDG Data Home directory 19 * @brief Retrieves the XDG Data Home directory
20 *
21 * This is where user-specific data files should be written
22 * ($XDG_DATA_HOME or $HOME/.local/share).
17 */ 23 */
18EAPI const char *efreet_data_home_get(void); 24EAPI const char *efreet_data_home_get(void);
19 25
@@ -21,6 +27,9 @@ EAPI const char *efreet_data_home_get(void);
21 * @return Returns the Eina_List of preference ordered extra data directories 27 * @return Returns the Eina_List of preference ordered extra data directories
22 * @brief Returns the Eina_List of preference ordered extra data directories 28 * @brief Returns the Eina_List of preference ordered extra data directories
23 * 29 *
30 * Ordered base directories relative to which data files should be
31 * searched ($XDG_DATA_DIRS or /usr/local/share/:/usr/share/)
32 *
24 * @note The returned list is static inside Efreet. If you add/remove from the 33 * @note The returned list is static inside Efreet. If you add/remove from the
25 * list then the next call to efreet_data_dirs_get() will return your 34 * list then the next call to efreet_data_dirs_get() will return your
26 * modified values. DO NOT free this list. 35 * modified values. DO NOT free this list.
@@ -31,12 +40,20 @@ EAPI Eina_List *efreet_data_dirs_get(void);
31/** 40/**
32 * @return Returns the XDG Config Home directory 41 * @return Returns the XDG Config Home directory
33 * @brief Retrieves the XDG Config Home directory 42 * @brief Retrieves the XDG Config Home directory
43 *
44 * This is where user-specific configuration files should be
45 * written ($XDG_CONFIG_HOME or $HOME/.config).
34 */ 46 */
35EAPI const char *efreet_config_home_get(void); 47EAPI const char *efreet_config_home_get(void);
36 48
37/** 49/**
38 * @return Returns the XDG Desktop directory 50 * @return Returns the XDG Desktop directory
39 * @brief Retrieves the XDG Desktop directory 51 * @brief Retrieves the XDG Desktop directory
52 *
53 * This is where user-specific desktop files should be located. It's
54 * localized (translated) to current user locale
55 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
56 *
40 * @since 1.3 57 * @since 1.3
41 */ 58 */
42EAPI const char *efreet_desktop_dir_get(void); 59EAPI const char *efreet_desktop_dir_get(void);
@@ -44,6 +61,19 @@ EAPI const char *efreet_desktop_dir_get(void);
44/** 61/**
45 * @return Returns the XDG Download directory 62 * @return Returns the XDG Download directory
46 * @brief Retrieves the XDG Download directory 63 * @brief Retrieves the XDG Download directory
64 *
65 * This is where user-specific download files should be located. It's
66 * localized (translated) to current user locale
67 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
68 *
69 * It's meant for large download or in-progress downloads, it's
70 * private for the user but may be shared among different
71 * machines. It's not automatically cleaned up.
72 *
73 * @see efreet_cache_home_get()
74 * @see efreet_runtime_dir_get()
75 * @see http://0pointer.de/blog/projects/tmp.html
76 *
47 * @since 1.8 77 * @since 1.8
48 */ 78 */
49EAPI const char *efreet_download_dir_get(void); 79EAPI const char *efreet_download_dir_get(void);
@@ -51,6 +81,16 @@ EAPI const char *efreet_download_dir_get(void);
51/** 81/**
52 * @return Returns the XDG Templates directory 82 * @return Returns the XDG Templates directory
53 * @brief Retrieves the XDG Templates directory 83 * @brief Retrieves the XDG Templates directory
84 *
85 * This is where user-specific template files should be located. It's
86 * localized (translated) to current user locale
87 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
88 *
89 * @see efreet_documents_dir_get()
90 * @see efreet_music_dir_get()
91 * @see efreet_pictures_dir_get()
92 * @see efreet_videos_dir_get()
93 *
54 * @since 1.8 94 * @since 1.8
55 */ 95 */
56EAPI const char *efreet_templates_dir_get(void); 96EAPI const char *efreet_templates_dir_get(void);
@@ -58,6 +98,13 @@ EAPI const char *efreet_templates_dir_get(void);
58/** 98/**
59 * @return Returns the XDG Public Share directory 99 * @return Returns the XDG Public Share directory
60 * @brief Retrieves the XDG Public Share directory 100 * @brief Retrieves the XDG Public Share directory
101 *
102 * This is where user-specific public shareable files should be
103 * located. It's localized (translated) to current user locale
104 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
105 *
106 * Usually local file servers should look here (Apache, Samba, FTP).
107 *
61 * @since 1.8 108 * @since 1.8
62 */ 109 */
63EAPI const char *efreet_public_share_dir_get(void); 110EAPI const char *efreet_public_share_dir_get(void);
@@ -65,6 +112,16 @@ EAPI const char *efreet_public_share_dir_get(void);
65/** 112/**
66 * @return Returns the XDG Documents directory 113 * @return Returns the XDG Documents directory
67 * @brief Retrieves the XDG Documents directory 114 * @brief Retrieves the XDG Documents directory
115 *
116 * This is where user-specific documents files should be located. It's
117 * localized (translated) to current user locale
118 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
119 *
120 * @see efreet_templates_dir_get()
121 * @see efreet_music_dir_get()
122 * @see efreet_pictures_dir_get()
123 * @see efreet_videos_dir_get()
124 *
68 * @since 1.8 125 * @since 1.8
69 */ 126 */
70EAPI const char *efreet_documents_dir_get(void); 127EAPI const char *efreet_documents_dir_get(void);
@@ -72,6 +129,16 @@ EAPI const char *efreet_documents_dir_get(void);
72/** 129/**
73 * @return Returns the XDG Music directory 130 * @return Returns the XDG Music directory
74 * @brief Retrieves the XDG Music directory 131 * @brief Retrieves the XDG Music directory
132 *
133 * This is where user-specific music files should be located. It's
134 * localized (translated) to current user locale
135 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
136 *
137 * @see efreet_templates_dir_get()
138 * @see efreet_download_dir_get()
139 * @see efreet_pictures_dir_get()
140 * @see efreet_videos_dir_get()
141 *
75 * @since 1.8 142 * @since 1.8
76 */ 143 */
77EAPI const char *efreet_music_dir_get(void); 144EAPI const char *efreet_music_dir_get(void);
@@ -79,6 +146,16 @@ EAPI const char *efreet_music_dir_get(void);
79/** 146/**
80 * @return Returns the XDG Pictures directory 147 * @return Returns the XDG Pictures directory
81 * @brief Retrieves the XDG Pictures directory 148 * @brief Retrieves the XDG Pictures directory
149 *
150 * This is where user-specific pictures files should be located. It's
151 * localized (translated) to current user locale
152 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
153 *
154 * @see efreet_templates_dir_get()
155 * @see efreet_documents_dir_get()
156 * @see efreet_music_dir_get()
157 * @see efreet_videos_dir_get()
158 *
82 * @since 1.8 159 * @since 1.8
83 */ 160 */
84EAPI const char *efreet_pictures_dir_get(void); 161EAPI const char *efreet_pictures_dir_get(void);
@@ -86,6 +163,16 @@ EAPI const char *efreet_pictures_dir_get(void);
86/** 163/**
87 * @return Returns the XDG Videos directory 164 * @return Returns the XDG Videos directory
88 * @brief Retrieves the XDG Videos directory 165 * @brief Retrieves the XDG Videos directory
166 *
167 * This is where user-specific video files should be located. It's
168 * localized (translated) to current user locale
169 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
170 *
171 * @see efreet_templates_dir_get()
172 * @see efreet_documents_dir_get()
173 * @see efreet_music_dir_get()
174 * @see efreet_pictures_dir_get()
175 *
89 * @since 1.8 176 * @since 1.8
90 */ 177 */
91EAPI const char *efreet_videos_dir_get(void); 178EAPI const char *efreet_videos_dir_get(void);
@@ -95,6 +182,9 @@ EAPI const char *efreet_videos_dir_get(void);
95 * @brief Returns the Eina_List of preference ordered extra config 182 * @brief Returns the Eina_List of preference ordered extra config
96 * directories 183 * directories
97 * 184 *
185 * Ordered base directories relative to which configuration files
186 * should be searched ($XDG_CONFIG_DIRS or /etc/xdg)
187 *
98 * @note The returned list is static inside Efreet. If you add/remove from the 188 * @note The returned list is static inside Efreet. If you add/remove from the
99 * list then the next call to efreet_config_dirs_get() will return your 189 * list then the next call to efreet_config_dirs_get() will return your
100 * modified values. DO NOT free this list. 190 * modified values. DO NOT free this list.
@@ -105,12 +195,60 @@ EAPI Eina_List *efreet_config_dirs_get(void);
105/** 195/**
106 * @return Returns the XDG Cache Home directory 196 * @return Returns the XDG Cache Home directory
107 * @brief Retrieves the XDG Cache Home directory 197 * @brief Retrieves the XDG Cache Home directory
198 *
199 * This is the base directory relative to which user specific
200 * non-essential data files should be stored ($XDG_CACHE_HOME or
201 * $HOME/.cache).
202 *
203 * @see efreet_runtime_dir_get()
204 * @see efreet_download_dir_get()
205 * @see efreet_config_home_get()
108 */ 206 */
109EAPI const char *efreet_cache_home_get(void); 207EAPI const char *efreet_cache_home_get(void);
110 208
111/** 209/**
112 * @return Returns the XDG User Runtime directory. 210 * @return Returns the XDG User Runtime directory.
113 * @brief Retrieves the XDG User Runtime directory. 211 * @brief Retrieves the XDG User Runtime directory.
212 *
213 * This is the base directory relative to which user-specific
214 * non-essential runtime files and other file objects (such as
215 * sockets, named pipes, ...) should be stored. The directory @b must
216 * be owned by the user, and he @b must be the only one having read
217 * and write access to it. Its Unix access mode @b must be 0700.
218 *
219 * The lifetime of this directory @b must be bound to the user being
220 * logged in. It @b must be created when the user first logs in and if
221 * the user fully logs out the directory @b must be removed. If the
222 * user logs in more than once he should get pointed to the same
223 * directory, and it is mandatory that the directory continues to
224 * exist from his first login to his last logout on the system, and
225 * not removed in between. Files in the directory @b must not survive
226 * reboot or a full logout/login cycle.
227 *
228 * The directory @b must be on a local file system and not shared with
229 * any other system. The directory @b must by fully-featured by the
230 * standards of the operating system. More specifically, on Unix-like
231 * operating systems AF_UNIX sockets, symbolic links, hard links,
232 * proper permissions, file locking, sparse files, memory mapping,
233 * file change notifications, a reliable hard link count must be
234 * supported, and no restrictions on the file name character set
235 * should be imposed. Files in this directory @b may be subjected to
236 * periodic clean-up. To ensure that your files are not removed, they
237 * should have their access time timestamp modified at least once
238 * every 6 hours of monotonic time or the 'sticky' bit should be set
239 * on the file.
240 *
241 * If @c NULL applications should fall back to a replacement directory
242 * with similar capabilities and print a warning message. Applications
243 * should use this directory for communication and synchronization
244 * purposes and should not place larger files in it, since it might
245 * reside in runtime memory and cannot necessarily be swapped out to
246 * disk.
247 *
248 * @note this directory is similar to @c /run and is often created in
249 * tmpfs (memory-only/RAM filesystem). It is created, managed and
250 * cleaned automatically by systemd.
251 *
114 * @since 1.8 252 * @since 1.8
115 */ 253 */
116EAPI const char *efreet_runtime_dir_get(void); 254EAPI const char *efreet_runtime_dir_get(void);