diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/eina/src/include/eina_file.h | 392 |
1 files changed, 392 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_file.h b/libraries/eina/src/include/eina_file.h new file mode 100644 index 0000000..01ef8f5 --- /dev/null +++ b/libraries/eina/src/include/eina_file.h | |||
@@ -0,0 +1,392 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2007-2008 Jorge Luis Zapata Muga | ||
3 | * 2011 Cedric Bail | ||
4 | * | ||
5 | * This library is free software; you can redistribute it and/or | ||
6 | * modify it under the terms of the GNU Lesser General Public | ||
7 | * License as published by the Free Software Foundation; either | ||
8 | * version 2.1 of the License, or (at your option) any later version. | ||
9 | * | ||
10 | * This library is distributed in the hope that it will be useful, | ||
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
13 | * Lesser General Public License for more details. | ||
14 | * | ||
15 | * You should have received a copy of the GNU Lesser General Public | ||
16 | * License along with this library; | ||
17 | * if not, see <http://www.gnu.org/licenses/>. | ||
18 | */ | ||
19 | |||
20 | #ifndef EINA_FILE_H_ | ||
21 | #define EINA_FILE_H_ | ||
22 | |||
23 | #include <limits.h> | ||
24 | #include <time.h> | ||
25 | |||
26 | #include "eina_types.h" | ||
27 | #include "eina_array.h" | ||
28 | #include "eina_iterator.h" | ||
29 | |||
30 | |||
31 | /** | ||
32 | * @page eina_file_example_01_page | ||
33 | * @dontinclude eina_file_01.c | ||
34 | * | ||
35 | * For brevity includes, variable declarations and initialization was omitted | ||
36 | * from this page, however the full source code can be seen @ref | ||
37 | * eina_file_example_01 "here". | ||
38 | * | ||
39 | * Here we have a simple callback to print the name of a file and the path that | ||
40 | * contains it: | ||
41 | * @skip static | ||
42 | * @until } | ||
43 | * | ||
44 | * We can use this callback in the following call: | ||
45 | * @skipline eina_file_dir_list | ||
46 | * | ||
47 | * The above was a way to print the files in a directory, but it is not the only | ||
48 | * one: | ||
49 | * @until iterator_free | ||
50 | * | ||
51 | * And now two ways to get more information than just file names: | ||
52 | * @until iterator_free | ||
53 | * @until iterator_free | ||
54 | * | ||
55 | * The above ways of getting files on a list may produce the same output, but | ||
56 | * they have an important difference, eina_file_direct_ls() will @b not call | ||
57 | * stat, this means that on some systems it might not have file type | ||
58 | * information. On the other hand it might be faster than eina_file_stat_ls(). | ||
59 | */ | ||
60 | /** | ||
61 | * @page eina_file_example_01 | ||
62 | * @include eina_file_01.c | ||
63 | * @example eina_file_01.c | ||
64 | */ | ||
65 | /** | ||
66 | * @addtogroup Eina_Tools_Group Tools | ||
67 | * | ||
68 | * @{ | ||
69 | */ | ||
70 | /** | ||
71 | * @addtogroup Eina_File_Group File | ||
72 | * | ||
73 | * @brief Functions to handle files and directories. | ||
74 | * | ||
75 | * This functions make it easier to do a number o file and directory operations | ||
76 | * such as getting the list of files in a directory, spliting paths and finding | ||
77 | * out file size and type. | ||
78 | * | ||
79 | * @warning All functions in this group are @b blocking which means they make | ||
80 | * take a long time to return, use them carefully. | ||
81 | * | ||
82 | * See an example @ref eina_file_example_01_page "here". | ||
83 | * | ||
84 | * @{ | ||
85 | */ | ||
86 | |||
87 | /** | ||
88 | * @typedef Eina_File_Direct_Info | ||
89 | * A typedef to #_Eina_File_Direct_Info. | ||
90 | */ | ||
91 | typedef struct _Eina_File_Direct_Info Eina_File_Direct_Info; | ||
92 | |||
93 | /** | ||
94 | * @typedef Eina_File_Dir_List_Cb | ||
95 | * Type for a callback to be called when iterating over the files of a | ||
96 | * directory. | ||
97 | */ | ||
98 | typedef void (*Eina_File_Dir_List_Cb)(const char *name, const char *path, void *data); | ||
99 | |||
100 | /** | ||
101 | * @typedef Eina_File_Type | ||
102 | * file type in Eina_File_Direct_Info. | ||
103 | */ | ||
104 | typedef enum { | ||
105 | EINA_FILE_UNKNOWN, /**< Unknown file type. */ | ||
106 | EINA_FILE_FIFO, /**< Named pipe (FIFO) type (unused on Windows). */ | ||
107 | EINA_FILE_CHR, /**< Character device type (unused on Windows). */ | ||
108 | EINA_FILE_DIR, /**< Directory type. */ | ||
109 | EINA_FILE_BLK, /**< Block device type (unused on Windows). */ | ||
110 | EINA_FILE_REG, /**< Regular file type. */ | ||
111 | EINA_FILE_LNK, /**< Symbolic link type. */ | ||
112 | EINA_FILE_SOCK, /**< UNIX domain socket type (unused on Windows). */ | ||
113 | EINA_FILE_WHT /**< Whiteout file type (unused on Windows). */ | ||
114 | } Eina_File_Type; | ||
115 | |||
116 | typedef struct _Eina_File Eina_File; | ||
117 | |||
118 | typedef enum { | ||
119 | EINA_FILE_RANDOM, /**< Advise random memory access to the mapped memory. */ | ||
120 | EINA_FILE_SEQUENTIAL, /**< Advise sequential memory access to the mapped memory. */ | ||
121 | EINA_FILE_WILLNEED, /**< Advise need for all the mapped memory. */ | ||
122 | EINA_FILE_POPULATE /**< Request all the mapped memory. */ | ||
123 | } Eina_File_Populate; | ||
124 | |||
125 | /* Why do this? Well PATH_MAX may vary from when eina itself is compiled | ||
126 | * to when the app using eina is compiled. exposing the path buffer below | ||
127 | * can't safely and portably vary based on how/when you compile. it should | ||
128 | * always be the same for both eina inside AND for apps outside that use eina | ||
129 | * so define this to 8192 - most PATH_MAX values are like 4096 or 1024 (with | ||
130 | * windows i think being 260), so 8192 should cover almost all cases. there | ||
131 | * is a possibility that PATH_MAX could be more than 8192. if anyone spots | ||
132 | * a path_max that is bigger - let us know, but, for now we will assume | ||
133 | * it never happens */ | ||
134 | #define EINA_PATH_MAX 8192 | ||
135 | /** | ||
136 | * @struct _Eina_File_Direct_Info | ||
137 | * A structure to store informations of a path. | ||
138 | */ | ||
139 | struct _Eina_File_Direct_Info | ||
140 | { | ||
141 | size_t path_length; /**< size of the whole path */ | ||
142 | size_t name_length; /**< size of the filename/basename component */ | ||
143 | size_t name_start; /**< where the filename/basename component starts */ | ||
144 | Eina_File_Type type; /**< file type */ | ||
145 | char path[EINA_PATH_MAX]; /**< the path */ | ||
146 | }; | ||
147 | |||
148 | /** | ||
149 | * @def EINA_FILE_DIR_LIST_CB | ||
150 | * @brief cast to an #Eina_File_Dir_List_Cb. | ||
151 | * | ||
152 | * @param function The function to cast. | ||
153 | * | ||
154 | * This macro casts @p function to Eina_File_Dir_List_Cb. | ||
155 | */ | ||
156 | #define EINA_FILE_DIR_LIST_CB(function) ((Eina_File_Dir_List_Cb)function) | ||
157 | |||
158 | |||
159 | /** | ||
160 | * @brief List all files on the directory calling the function for every file found. | ||
161 | * | ||
162 | * @param dir The directory name. | ||
163 | * @param recursive Iterate recursively in the directory. | ||
164 | * @param cb The callback to be called. | ||
165 | * @param data The data to pass to the callback. | ||
166 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
167 | * | ||
168 | * This function calls @p cb for each file that is in @p dir. To have @p cb | ||
169 | * called on files that are in subdirectories of @p dir @p recursive should be | ||
170 | * EINA_TRUE. In other words if @p recursive is EINA_FALSE, only direct children | ||
171 | * of @p dir will be operated on, if @p recursive is EINA_TRUE the entire tree | ||
172 | * of files that is below @p dir will be operated on. | ||
173 | * | ||
174 | * If @p cb or @p dir are @c NULL, or if @p dir is a string of size 0, | ||
175 | * or if @p dir can not be opened, this function returns #EINA_FALSE | ||
176 | * immediately. otherwise, it returns #EINA_TRUE. | ||
177 | */ | ||
178 | EAPI Eina_Bool eina_file_dir_list(const char *dir, | ||
179 | Eina_Bool recursive, | ||
180 | Eina_File_Dir_List_Cb cb, | ||
181 | void *data) EINA_ARG_NONNULL(1, 3); | ||
182 | |||
183 | /** | ||
184 | * @brief Split a path according to the delimiter of the filesystem. | ||
185 | * | ||
186 | * @param path The path to split. | ||
187 | * @return An array of the parts of the path to split. | ||
188 | * | ||
189 | * This function splits @p path according to the delimiter of the used | ||
190 | * filesystem. If @p path is @c NULL or if the array can not be | ||
191 | * created, @c NULL is returned, otherwise, an array with each part of @p path | ||
192 | * is returned. | ||
193 | */ | ||
194 | EAPI Eina_Array *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | ||
195 | |||
196 | /** | ||
197 | * @brief Get an iterator to list the content of a directory. | ||
198 | * | ||
199 | * @param dir The name of the directory to list | ||
200 | * @return Return an Eina_Iterator that will walk over the files and directories | ||
201 | * in @p dir. On failure it will return NULL. | ||
202 | * | ||
203 | * Returns an iterator for shared strings, the name of each file in @p dir will | ||
204 | * only be fetched when advancing the iterator, which means there is very little | ||
205 | * cost associated with creating the list and stopping halfway through it. | ||
206 | * | ||
207 | * @warning The iterator will hand the user a stringshared value with the full | ||
208 | * path. The user must free the string using eina_stringshare_del() on it. | ||
209 | * | ||
210 | * @note The container for the iterator is of type DIR*. | ||
211 | * @note The iterator will walk over '.' and '..' without returning them. | ||
212 | * | ||
213 | * @see eina_file_direct_ls() | ||
214 | */ | ||
215 | EAPI Eina_Iterator *eina_file_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | ||
216 | |||
217 | /** | ||
218 | * @brief Get an iterator to list the content of a directory, with direct | ||
219 | * information. | ||
220 | * | ||
221 | * @param dir The name of the directory to list | ||
222 | * | ||
223 | * @return Return an Eina_Iterator that will walk over the files and | ||
224 | * directory in the pointed directory. On failure it will | ||
225 | * return NULL. | ||
226 | * | ||
227 | * Returns an iterator for Eina_File_Direct_Info, the name of each file in @p | ||
228 | * dir will only be fetched when advancing the iterator, which means there is | ||
229 | * cost associated with creating the list and stopping halfway through it. | ||
230 | * | ||
231 | * @warning The Eina_File_Direct_Info returned by the iterator <b>must not</b> | ||
232 | * be modified in any way. | ||
233 | * @warning When the iterator is advanced or deleted the Eina_File_Direct_Info | ||
234 | * returned is no longer valid. | ||
235 | * | ||
236 | * @note The container for the iterator is of type DIR*. | ||
237 | * @note The iterator will walk over '.' and '..' without returning them. | ||
238 | * @note The difference between this function ahd eina_file_direct_ls() is that | ||
239 | * it guarantees the file type information will be correct incurring a | ||
240 | * possible performance penalty. | ||
241 | * | ||
242 | * @see eina_file_direct_ls() | ||
243 | */ | ||
244 | EAPI Eina_Iterator *eina_file_stat_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | ||
245 | |||
246 | /** | ||
247 | * @brief Get an iterator to list the content of a directory, with direct | ||
248 | * information. | ||
249 | * | ||
250 | * @param dir The name of the directory to list | ||
251 | * | ||
252 | * @return Return an Eina_Iterator that will walk over the files and | ||
253 | * directory in the pointed directory. On failure it will | ||
254 | * return NULL. | ||
255 | * | ||
256 | * Returns an iterator for Eina_File_Direct_Info, the name of each file in @p | ||
257 | * dir will only be fetched when advancing the iterator, which means there is | ||
258 | * cost associated with creating the list and stopping halfway through it. | ||
259 | * | ||
260 | * @warning If readdir_r doesn't contain file type information file type will | ||
261 | * be DT_UNKNOW. | ||
262 | * @warning The Eina_File_Direct_Info returned by the iterator <b>must not</b> | ||
263 | * be modified in any way. | ||
264 | * @warning When the iterator is advanced or deleted the Eina_File_Direct_Info | ||
265 | * returned is no longer valid. | ||
266 | * | ||
267 | * @note The container for the iterator is of type DIR*. | ||
268 | * @note The iterator will walk over '.' and '..' without returning them. | ||
269 | * @note The difference between this function ahd eina_file_stat_ls() is that | ||
270 | * it may not get the file type information however it is likely to be | ||
271 | * faster. | ||
272 | * | ||
273 | * @see eina_file_ls() | ||
274 | */ | ||
275 | EAPI Eina_Iterator *eina_file_direct_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | ||
276 | |||
277 | /** | ||
278 | * @brief Sanitize file path. | ||
279 | * | ||
280 | * @param path The path to sanitize | ||
281 | * | ||
282 | * @return an allocated string with the sanitized path. | ||
283 | * | ||
284 | * This function take care of adding the current working directory if it's a | ||
285 | * relative path and also remove all '..' and '//' reference in the original | ||
286 | * path. | ||
287 | * | ||
288 | * @since 1.1 | ||
289 | */ | ||
290 | EAPI char *eina_file_path_sanitize(const char *path); | ||
291 | |||
292 | /** | ||
293 | * @brief Get a read-only handler to a file. | ||
294 | * | ||
295 | * @param name Filename to open | ||
296 | * @param shared Requested a shm | ||
297 | * | ||
298 | * Opens a file in read-only mode. @p name should be an absolute path. An | ||
299 | * Eina_File handle can be shared among multiple instances if @p shared is | ||
300 | * EINA_TRUE. | ||
301 | * | ||
302 | * @since 1.1 | ||
303 | */ | ||
304 | EAPI Eina_File *eina_file_open(const char *name, Eina_Bool shared) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | ||
305 | |||
306 | /** | ||
307 | * @brief Unref file handler. | ||
308 | * | ||
309 | * @param file File handler to unref. | ||
310 | * | ||
311 | * Decremente file's refcount and if it reaches zero close it. | ||
312 | * | ||
313 | * @since 1.1 | ||
314 | */ | ||
315 | EAPI void eina_file_close(Eina_File *file); | ||
316 | |||
317 | /** | ||
318 | * @brief Get file size at open time. | ||
319 | * | ||
320 | * @param file The file handler to request the size from. | ||
321 | * @return The length of the file. | ||
322 | * | ||
323 | * @since 1.1 | ||
324 | */ | ||
325 | EAPI size_t eina_file_size_get(Eina_File *file); | ||
326 | |||
327 | /** | ||
328 | * @brief Get the last modification time of an open file. | ||
329 | * | ||
330 | * @param file The file handler to request the modification time from. | ||
331 | * @return The last modification time. | ||
332 | * | ||
333 | * @since 1.1 | ||
334 | */ | ||
335 | EAPI time_t eina_file_mtime_get(Eina_File *file); | ||
336 | |||
337 | /** | ||
338 | * @brief Get the filename of an open file. | ||
339 | * | ||
340 | * @param file The file handler to request the name from. | ||
341 | * @return Stringshared filename of the file. | ||
342 | * | ||
343 | * @since 1.1 | ||
344 | */ | ||
345 | EAPI const char *eina_file_filename_get(Eina_File *file); | ||
346 | |||
347 | /** | ||
348 | * @brief Map all the file to a buffer. | ||
349 | * | ||
350 | * @param file The file handler to map in memory | ||
351 | * @param rule The rule to apply to the mapped memory | ||
352 | * @return A pointer to a buffer that map all the file content. @c NULL if it fail. | ||
353 | * | ||
354 | * @since 1.1 | ||
355 | */ | ||
356 | EAPI void *eina_file_map_all(Eina_File *file, Eina_File_Populate rule); | ||
357 | |||
358 | /** | ||
359 | * @brief Map a part of the file. | ||
360 | * | ||
361 | * @param file The file handler to map in memory | ||
362 | * @param rule The rule to apply to the mapped memory | ||
363 | * @param offset The offset inside the file | ||
364 | * @param length The length of the memory to map | ||
365 | * @return A valid pointer to the system memory with @p length valid byte in it. And @c NULL if not inside the file or anything else goes wrong. | ||
366 | * | ||
367 | * This does handle refcounting so it will share map that target the same memory area. | ||
368 | * | ||
369 | * @since 1.1 | ||
370 | */ | ||
371 | EAPI void *eina_file_map_new(Eina_File *file, Eina_File_Populate rule, | ||
372 | unsigned long int offset, unsigned long int length); | ||
373 | |||
374 | /** | ||
375 | * @brief Unref and unmap memory if possible. | ||
376 | * | ||
377 | * @param file The file handler to unmap memory from. | ||
378 | * @param map Memory map to unref and unmap. | ||
379 | * | ||
380 | * @since 1.1 | ||
381 | */ | ||
382 | EAPI void eina_file_map_free(Eina_File *file, void *map); | ||
383 | |||
384 | /** | ||
385 | * @} | ||
386 | */ | ||
387 | |||
388 | /** | ||
389 | * @} | ||
390 | */ | ||
391 | |||
392 | #endif /* EINA_FILE_H_ */ | ||