diff options
Diffstat (limited to 'libraries/eina/src/include/eina_file.h')
-rw-r--r-- | libraries/eina/src/include/eina_file.h | 483 |
1 files changed, 0 insertions, 483 deletions
diff --git a/libraries/eina/src/include/eina_file.h b/libraries/eina/src/include/eina_file.h deleted file mode 100644 index 1af22af..0000000 --- a/libraries/eina/src/include/eina_file.h +++ /dev/null | |||
@@ -1,483 +0,0 @@ | |||
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 | #include <sys/stat.h> | ||
26 | |||
27 | #include "eina_types.h" | ||
28 | #include "eina_array.h" | ||
29 | #include "eina_iterator.h" | ||
30 | |||
31 | |||
32 | /** | ||
33 | * @page eina_file_example_01_page | ||
34 | * @dontinclude eina_file_01.c | ||
35 | * | ||
36 | * For brevity includes, variable declarations and initialization was omitted | ||
37 | * from this page, however the full source code can be seen @ref | ||
38 | * eina_file_example_01 "here". | ||
39 | * | ||
40 | * Here we have a simple callback to print the name of a file and the path that | ||
41 | * contains it: | ||
42 | * @skip static | ||
43 | * @until } | ||
44 | * | ||
45 | * We can use this callback in the following call: | ||
46 | * @skipline eina_file_dir_list | ||
47 | * | ||
48 | * The above was a way to print the files in a directory, but it is not the only | ||
49 | * one: | ||
50 | * @until iterator_free | ||
51 | * | ||
52 | * And now two ways to get more information than just file names: | ||
53 | * @until iterator_free | ||
54 | * @until iterator_free | ||
55 | * | ||
56 | * The above ways of getting files on a list may produce the same output, but | ||
57 | * they have an important difference, eina_file_direct_ls() will @b not call | ||
58 | * stat, this means that on some systems it might not have file type | ||
59 | * information. On the other hand it might be faster than eina_file_stat_ls(). | ||
60 | */ | ||
61 | /** | ||
62 | * @page eina_file_example_01 | ||
63 | * @include eina_file_01.c | ||
64 | * @example eina_file_01.c | ||
65 | */ | ||
66 | /** | ||
67 | * @addtogroup Eina_Tools_Group Tools | ||
68 | * | ||
69 | * @{ | ||
70 | */ | ||
71 | /** | ||
72 | * @addtogroup Eina_File_Group File | ||
73 | * | ||
74 | * @brief Functions to handle files and directories. | ||
75 | * | ||
76 | * This functions make it easier to do a number o file and directory operations | ||
77 | * such as getting the list of files in a directory, spliting paths and finding | ||
78 | * out file size and type. | ||
79 | * | ||
80 | * @warning All functions in this group are @b blocking which means they make | ||
81 | * take a long time to return, use them carefully. | ||
82 | * | ||
83 | * See an example @ref eina_file_example_01_page "here". | ||
84 | * | ||
85 | * @{ | ||
86 | */ | ||
87 | |||
88 | /** | ||
89 | * @typedef Eina_File_Direct_Info | ||
90 | * A typedef to #_Eina_File_Direct_Info. | ||
91 | */ | ||
92 | typedef struct _Eina_File_Direct_Info Eina_File_Direct_Info; | ||
93 | |||
94 | /** | ||
95 | * @typedef Eina_Stat | ||
96 | * A typedef to #_Eina_Stat. | ||
97 | * @since 1.2 | ||
98 | */ | ||
99 | typedef struct _Eina_Stat Eina_Stat; | ||
100 | |||
101 | /** | ||
102 | * @typedef Eina_File_Dir_List_Cb | ||
103 | * Type for a callback to be called when iterating over the files of a | ||
104 | * directory. | ||
105 | * @param The file name EXCLUDING the path | ||
106 | * @param path The path passed to eina_file_dir_list() | ||
107 | * @param data The data passed to eina_file_dir_list() | ||
108 | */ | ||
109 | typedef void (*Eina_File_Dir_List_Cb)(const char *name, const char *path, void *data); | ||
110 | |||
111 | /** | ||
112 | * @typedef Eina_File_Type | ||
113 | * file type in Eina_File_Direct_Info. | ||
114 | */ | ||
115 | typedef enum { | ||
116 | EINA_FILE_UNKNOWN, /**< Unknown file type. */ | ||
117 | EINA_FILE_FIFO, /**< Named pipe (FIFO) type (unused on Windows). */ | ||
118 | EINA_FILE_CHR, /**< Character device type (unused on Windows). */ | ||
119 | EINA_FILE_DIR, /**< Directory type. */ | ||
120 | EINA_FILE_BLK, /**< Block device type (unused on Windows). */ | ||
121 | EINA_FILE_REG, /**< Regular file type. */ | ||
122 | EINA_FILE_LNK, /**< Symbolic link type. */ | ||
123 | EINA_FILE_SOCK, /**< UNIX domain socket type (unused on Windows). */ | ||
124 | EINA_FILE_WHT /**< Whiteout file type (unused on Windows). */ | ||
125 | } Eina_File_Type; | ||
126 | |||
127 | typedef struct _Eina_File Eina_File; | ||
128 | |||
129 | typedef enum { | ||
130 | EINA_FILE_RANDOM, /**< Advise random memory access to the mapped memory. */ | ||
131 | EINA_FILE_SEQUENTIAL, /**< Advise sequential memory access to the mapped memory. */ | ||
132 | EINA_FILE_WILLNEED, /**< Advise need for all the mapped memory. */ | ||
133 | EINA_FILE_POPULATE /**< Request all the mapped memory. */ | ||
134 | } Eina_File_Populate; | ||
135 | |||
136 | /* Why do this? Well PATH_MAX may vary from when eina itself is compiled | ||
137 | * to when the app using eina is compiled. exposing the path buffer below | ||
138 | * can't safely and portably vary based on how/when you compile. it should | ||
139 | * always be the same for both eina inside AND for apps outside that use eina | ||
140 | * so define this to 8192 - most PATH_MAX values are like 4096 or 1024 (with | ||
141 | * windows i think being 260), so 8192 should cover almost all cases. there | ||
142 | * is a possibility that PATH_MAX could be more than 8192. if anyone spots | ||
143 | * a path_max that is bigger - let us know, but, for now we will assume | ||
144 | * it never happens */ | ||
145 | #define EINA_PATH_MAX 8192 | ||
146 | /** | ||
147 | * @struct _Eina_File_Direct_Info | ||
148 | * A structure to store informations of a path. | ||
149 | */ | ||
150 | struct _Eina_File_Direct_Info | ||
151 | { | ||
152 | size_t path_length; /**< size of the whole path */ | ||
153 | size_t name_length; /**< size of the filename/basename component */ | ||
154 | size_t name_start; /**< where the filename/basename component starts */ | ||
155 | Eina_File_Type type; /**< file type */ | ||
156 | char path[EINA_PATH_MAX]; /**< the path */ | ||
157 | }; | ||
158 | |||
159 | /** | ||
160 | * @struct _Eina_Stat | ||
161 | * A structure to store informations of a path. | ||
162 | * @since 1.2 | ||
163 | */ | ||
164 | struct _Eina_Stat | ||
165 | { | ||
166 | unsigned long int dev; | ||
167 | unsigned long int ino; | ||
168 | unsigned int mode; | ||
169 | unsigned int nlink; | ||
170 | unsigned int uid; | ||
171 | unsigned int gid; | ||
172 | unsigned long int rdev; | ||
173 | unsigned long int size; | ||
174 | unsigned long int blksize; | ||
175 | unsigned long int blocks; | ||
176 | unsigned long int atime; | ||
177 | unsigned long int atimensec; | ||
178 | unsigned long int mtime; | ||
179 | unsigned long int mtimensec; | ||
180 | unsigned long int ctime; | ||
181 | unsigned long int ctimensec; | ||
182 | }; | ||
183 | |||
184 | /** | ||
185 | * @def EINA_FILE_DIR_LIST_CB | ||
186 | * @brief cast to an #Eina_File_Dir_List_Cb. | ||
187 | * | ||
188 | * @param function The function to cast. | ||
189 | * | ||
190 | * This macro casts @p function to Eina_File_Dir_List_Cb. | ||
191 | */ | ||
192 | #define EINA_FILE_DIR_LIST_CB(function) ((Eina_File_Dir_List_Cb)function) | ||
193 | |||
194 | |||
195 | /** | ||
196 | * @brief List all files on the directory calling the function for every file found. | ||
197 | * | ||
198 | * @param dir The directory name. | ||
199 | * @param recursive Iterate recursively in the directory. | ||
200 | * @param cb The callback to be called. | ||
201 | * @param data The data to pass to the callback. | ||
202 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
203 | * | ||
204 | * This function calls @p cb for each file that is in @p dir. To have @p cb | ||
205 | * called on files that are in subdirectories of @p dir @p recursive should be | ||
206 | * EINA_TRUE. In other words if @p recursive is EINA_FALSE, only direct children | ||
207 | * of @p dir will be operated on, if @p recursive is EINA_TRUE the entire tree | ||
208 | * of files that is below @p dir will be operated on. | ||
209 | * | ||
210 | * If @p cb or @p dir are @c NULL, or if @p dir is a string of size 0, | ||
211 | * or if @p dir can not be opened, this function returns #EINA_FALSE | ||
212 | * immediately. otherwise, it returns #EINA_TRUE. | ||
213 | */ | ||
214 | EAPI Eina_Bool eina_file_dir_list(const char *dir, | ||
215 | Eina_Bool recursive, | ||
216 | Eina_File_Dir_List_Cb cb, | ||
217 | void *data) EINA_ARG_NONNULL(1, 3); | ||
218 | |||
219 | /** | ||
220 | * @brief Split a path according to the delimiter of the filesystem. | ||
221 | * | ||
222 | * @param path The path to split. | ||
223 | * @return An array of the parts of the path to split. | ||
224 | * | ||
225 | * This function splits @p path according to the delimiter of the used | ||
226 | * filesystem. If @p path is @c NULL or if the array can not be | ||
227 | * created, @c NULL is returned, otherwise, an array with each part of @p path | ||
228 | * is returned. | ||
229 | */ | ||
230 | EAPI Eina_Array *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | ||
231 | |||
232 | /** | ||
233 | * @brief Get an iterator to list the content of a directory. | ||
234 | * | ||
235 | * @param dir The name of the directory to list | ||
236 | * @return Return an Eina_Iterator that will walk over the files and directories | ||
237 | * in @p dir. On failure it will return NULL. | ||
238 | * | ||
239 | * Returns an iterator for shared strings, the name of each file in @p dir will | ||
240 | * only be fetched when advancing the iterator, which means there is very little | ||
241 | * cost associated with creating the list and stopping halfway through it. | ||
242 | * | ||
243 | * @warning The iterator will hand the user a stringshared value with the full | ||
244 | * path. The user must free the string using eina_stringshare_del() on it. | ||
245 | * | ||
246 | * @note The container for the iterator is of type DIR*. | ||
247 | * @note The iterator will walk over '.' and '..' without returning them. | ||
248 | * | ||
249 | * @see eina_file_direct_ls() | ||
250 | */ | ||
251 | EAPI Eina_Iterator *eina_file_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | ||
252 | |||
253 | /** | ||
254 | * @brief Get an iterator to list the content of a directory, with direct | ||
255 | * information. | ||
256 | * | ||
257 | * @param dir The name of the directory to list | ||
258 | * | ||
259 | * @return Return an Eina_Iterator that will walk over the files and | ||
260 | * directory in the pointed directory. On failure it will | ||
261 | * return NULL. | ||
262 | * | ||
263 | * Returns an iterator for Eina_File_Direct_Info, the name of each file in @p | ||
264 | * dir will only be fetched when advancing the iterator, which means there is | ||
265 | * cost associated with creating the list and stopping halfway through it. | ||
266 | * | ||
267 | * @warning The Eina_File_Direct_Info returned by the iterator <b>must not</b> | ||
268 | * be modified in any way. | ||
269 | * @warning When the iterator is advanced or deleted the Eina_File_Direct_Info | ||
270 | * returned is no longer valid. | ||
271 | * | ||
272 | * @note The container for the iterator is of type DIR*. | ||
273 | * @note The iterator will walk over '.' and '..' without returning them. | ||
274 | * @note The difference between this function ahd eina_file_direct_ls() is that | ||
275 | * it guarantees the file type information will be correct incurring a | ||
276 | * possible performance penalty. | ||
277 | * | ||
278 | * @see eina_file_direct_ls() | ||
279 | */ | ||
280 | EAPI Eina_Iterator *eina_file_stat_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | ||
281 | |||
282 | /** | ||
283 | * @brief Use information provided by Eina_Iterator of eina_file_stat_ls or eina_file_direct_ls | ||
284 | * to call stat in the most efficient way on your system. | ||
285 | * | ||
286 | * @param container The container returned by the Eina_Iterator using eina_iterator_container_get(). | ||
287 | * @param info The content of the current Eina_File_Direct_Info provided by the Eina_Iterator | ||
288 | * @param buf Where to put the result of the stat | ||
289 | * @return On success 0 is returned, On error -1 is returned and errno is set appropriately. | ||
290 | * | ||
291 | * This function calls fstatat or stat depending on what your system supports. This makes it efficient and simple | ||
292 | * to use on your side without complex detection already done inside Eina on what the system can do. | ||
293 | * | ||
294 | * @see eina_file_direct_ls() | ||
295 | * @see eina_file_stat_ls() | ||
296 | * @since 1.2 | ||
297 | */ | ||
298 | EAPI int eina_file_statat(void *container, Eina_File_Direct_Info *info, Eina_Stat *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2, 3); | ||
299 | |||
300 | /** | ||
301 | * @brief Get an iterator to list the content of a directory, with direct | ||
302 | * information. | ||
303 | * | ||
304 | * @param dir The name of the directory to list | ||
305 | * | ||
306 | * @return Return an Eina_Iterator that will walk over the files and | ||
307 | * directory in the pointed directory. On failure it will | ||
308 | * return NULL. | ||
309 | * | ||
310 | * Returns an iterator for Eina_File_Direct_Info, the name of each file in @p | ||
311 | * dir will only be fetched when advancing the iterator, which means there is | ||
312 | * cost associated with creating the list and stopping halfway through it. | ||
313 | * | ||
314 | * @warning If readdir_r doesn't contain file type information file type will | ||
315 | * be DT_UNKNOW. | ||
316 | * @warning The Eina_File_Direct_Info returned by the iterator <b>must not</b> | ||
317 | * be modified in any way. | ||
318 | * @warning When the iterator is advanced or deleted the Eina_File_Direct_Info | ||
319 | * returned is no longer valid. | ||
320 | * | ||
321 | * @note The container for the iterator is of type DIR*. | ||
322 | * @note The iterator will walk over '.' and '..' without returning them. | ||
323 | * @note The difference between this function ahd eina_file_stat_ls() is that | ||
324 | * it may not get the file type information however it is likely to be | ||
325 | * faster. | ||
326 | * | ||
327 | * @see eina_file_ls() | ||
328 | */ | ||
329 | EAPI Eina_Iterator *eina_file_direct_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | ||
330 | |||
331 | /** | ||
332 | * @brief Sanitize file path. | ||
333 | * | ||
334 | * @param path The path to sanitize | ||
335 | * | ||
336 | * @return an allocated string with the sanitized path. | ||
337 | * | ||
338 | * This function take care of adding the current working directory if it's a | ||
339 | * relative path and also remove all '..' and '//' reference in the original | ||
340 | * path. | ||
341 | * | ||
342 | * @since 1.1 | ||
343 | */ | ||
344 | EAPI char *eina_file_path_sanitize(const char *path); | ||
345 | |||
346 | /** | ||
347 | * @brief Get a read-only handler to a file. | ||
348 | * | ||
349 | * @param name Filename to open | ||
350 | * @param shared Requested a shm | ||
351 | * | ||
352 | * Opens a file in read-only mode. @p name should be an absolute path. An | ||
353 | * Eina_File handle can be shared among multiple instances if @p shared is | ||
354 | * EINA_TRUE. | ||
355 | * | ||
356 | * @since 1.1 | ||
357 | */ | ||
358 | EAPI Eina_File *eina_file_open(const char *name, Eina_Bool shared) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | ||
359 | |||
360 | /** | ||
361 | * @brief Unref file handler. | ||
362 | * | ||
363 | * @param file File handler to unref. | ||
364 | * | ||
365 | * Decremente file's refcount and if it reaches zero close it. | ||
366 | * | ||
367 | * @since 1.1 | ||
368 | */ | ||
369 | EAPI void eina_file_close(Eina_File *file); | ||
370 | |||
371 | /** | ||
372 | * @brief Get file size at open time. | ||
373 | * | ||
374 | * @param file The file handler to request the size from. | ||
375 | * @return The length of the file. | ||
376 | * | ||
377 | * @since 1.1 | ||
378 | */ | ||
379 | EAPI size_t eina_file_size_get(Eina_File *file); | ||
380 | |||
381 | /** | ||
382 | * @brief Get the last modification time of an open file. | ||
383 | * | ||
384 | * @param file The file handler to request the modification time from. | ||
385 | * @return The last modification time. | ||
386 | * | ||
387 | * @since 1.1 | ||
388 | */ | ||
389 | EAPI time_t eina_file_mtime_get(Eina_File *file); | ||
390 | |||
391 | /** | ||
392 | * @brief Get the filename of an open file. | ||
393 | * | ||
394 | * @param file The file handler to request the name from. | ||
395 | * @return Stringshared filename of the file. | ||
396 | * | ||
397 | * @since 1.1 | ||
398 | */ | ||
399 | EAPI const char *eina_file_filename_get(Eina_File *file); | ||
400 | |||
401 | /** | ||
402 | * @brief Get the eXtended attribute of an open file. | ||
403 | * | ||
404 | * @param file The file handler to request the eXtended attribute from. | ||
405 | * @return an iterator. | ||
406 | * | ||
407 | * The iterator will list all eXtended attribute name without allocating | ||
408 | * them, so you need to copy them yourself if needed. | ||
409 | * | ||
410 | * @since 1.2 | ||
411 | */ | ||
412 | EAPI Eina_Iterator *eina_file_xattr_get(Eina_File *file); | ||
413 | |||
414 | /** | ||
415 | * @brief Get the eXtended attribute of an open file. | ||
416 | * | ||
417 | * @param file The file handler to request the eXtended attribute from. | ||
418 | * @return an iterator. | ||
419 | * | ||
420 | * The iterator will list all eXtended attribute without allocating | ||
421 | * them, so you need to copy them yourself if needed. It is returning | ||
422 | * Eina_Xattr structure. | ||
423 | * | ||
424 | * @since 1.2 | ||
425 | */ | ||
426 | EAPI Eina_Iterator *eina_file_xattr_value_get(Eina_File *file); | ||
427 | |||
428 | /** | ||
429 | * @brief Map all the file to a buffer. | ||
430 | * | ||
431 | * @param file The file handler to map in memory | ||
432 | * @param rule The rule to apply to the mapped memory | ||
433 | * @return A pointer to a buffer that map all the file content. @c NULL if it fail. | ||
434 | * | ||
435 | * @since 1.1 | ||
436 | */ | ||
437 | EAPI void *eina_file_map_all(Eina_File *file, Eina_File_Populate rule); | ||
438 | |||
439 | /** | ||
440 | * @brief Map a part of the file. | ||
441 | * | ||
442 | * @param file The file handler to map in memory | ||
443 | * @param rule The rule to apply to the mapped memory | ||
444 | * @param offset The offset inside the file | ||
445 | * @param length The length of the memory to map | ||
446 | * @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. | ||
447 | * | ||
448 | * This does handle refcounting so it will share map that target the same memory area. | ||
449 | * | ||
450 | * @since 1.1 | ||
451 | */ | ||
452 | EAPI void *eina_file_map_new(Eina_File *file, Eina_File_Populate rule, | ||
453 | unsigned long int offset, unsigned long int length); | ||
454 | |||
455 | /** | ||
456 | * @brief Unref and unmap memory if possible. | ||
457 | * | ||
458 | * @param file The file handler to unmap memory from. | ||
459 | * @param map Memory map to unref and unmap. | ||
460 | * | ||
461 | * @since 1.1 | ||
462 | */ | ||
463 | EAPI void eina_file_map_free(Eina_File *file, void *map); | ||
464 | |||
465 | /** | ||
466 | * @brief Tell if their was an IO error during the life of a mmaped file | ||
467 | * | ||
468 | * @param file The file handler to the mmaped file. | ||
469 | * @param map Memory map to check if an error occured on it. | ||
470 | * | ||
471 | * @since 1.2 | ||
472 | */ | ||
473 | EAPI Eina_Bool eina_file_map_faulted(Eina_File *file, void *map); | ||
474 | |||
475 | /** | ||
476 | * @} | ||
477 | */ | ||
478 | |||
479 | /** | ||
480 | * @} | ||
481 | */ | ||
482 | |||
483 | #endif /* EINA_FILE_H_ */ | ||