summaryrefslogtreecommitdiff
path: root/legacy/eina
diff options
context:
space:
mode:
authorJonas M. Gastal <jgastal@profusion.mobi>2011-06-22 19:25:44 +0000
committerJonas M. Gastal <jgastal@profusion.mobi>2011-06-22 19:25:44 +0000
commitdbe4c5d613c804b98614db34528e82585d10125b (patch)
tree8692232e0e81e19ff75c3bbeaa3aa640f6b44286 /legacy/eina
parentd83f1749299d167df01b2752509aff4f4cb949d8 (diff)
Eina: Eina file documentation.
SVN revision: 60604
Diffstat (limited to 'legacy/eina')
-rw-r--r--legacy/eina/src/examples/eina_file_01.c45
-rw-r--r--legacy/eina/src/include/eina_file.h177
2 files changed, 146 insertions, 76 deletions
diff --git a/legacy/eina/src/examples/eina_file_01.c b/legacy/eina/src/examples/eina_file_01.c
new file mode 100644
index 0000000000..6490b623c2
--- /dev/null
+++ b/legacy/eina/src/examples/eina_file_01.c
@@ -0,0 +1,45 @@
1//Compile with:
2//gcc -g `pkg-config --cflags --libs eina` eina_file_01.c -o eina_file_01
3
4#include <stdio.h>
5#include <Eina.h>
6
7static void
8_print_cb(const char *name, const char *path, void *data)
9{
10 printf("file %s in %s\n", name, path);
11}
12
13int
14main(int argc, char **argv)
15{
16 Eina_Iterator *it;
17 const char *f_name;
18 const Eina_File_Direct_Info *f_info;
19
20 eina_init();
21
22 eina_file_dir_list("/home/", EINA_FALSE, _print_cb, NULL);
23
24 it = eina_file_ls("/home/");
25 EINA_ITERATOR_FOREACH(it, f_name)
26 {
27 printf("%s\n", f_name);
28 eina_stringshare_del(f_name);
29 }
30 eina_iterator_free(it);
31
32 it = eina_file_stat_ls("/home/");
33 EINA_ITERATOR_FOREACH(it, f_info)
34 printf("%s if of type %d\n", f_info->path, f_info->type);
35 eina_iterator_free(it);
36
37 it = eina_file_direct_ls("/home/");
38 EINA_ITERATOR_FOREACH(it, f_info)
39 printf("%s if of type %d\n", f_info->path, f_info->type);
40 eina_iterator_free(it);
41
42 eina_shutdown();
43
44 return 0;
45}
diff --git a/legacy/eina/src/include/eina_file.h b/legacy/eina/src/include/eina_file.h
index a75ddac37c..e02e501d80 100644
--- a/legacy/eina/src/include/eina_file.h
+++ b/legacy/eina/src/include/eina_file.h
@@ -28,27 +28,57 @@
28 28
29 29
30/** 30/**
31 * @addtogroup Eina_File_Group File 31 * @page eina_file_example_01_page
32 * @dontinclude eina_file_01.c
32 * 33 *
33 * @brief Functions to traverse directories and split paths. 34 * For brevity includes, variable declarations and initialization was ommited
35 * from this page, however the full source code can be seen @ref
36 * eina_file_example_01 "here".
34 * 37 *
35 * @li eina_file_dir_list() list the content of a directory, 38 * Here we have a simple callback to print the name of a file and the path that
36 * recusrsively or not, and can call a callback function for eachfound 39 * contains it:
37 * file. 40 * @skip static
38 * @li eina_file_split() split a path into all the subdirectories that 41 * @until }
39 * compose it, according to the separator of the file system.
40 * 42 *
41 * @{ 43 * We can use this callback in the following call:
44 * @skipline eina_file_dir_list
45 *
46 * The above was a way to print the files in a directory, but it is not the only
47 * one:
48 * @until iterator_free
49 *
50 * And now two ways to get more information than just file names:
51 * @until iterator_free
52 * @until iterator_free
53 *
54 * The above ways of getting files on a list may produce the same output, but
55 * they have an important difference, eina_file_direct_ls() will @b not call
56 * stat, this means that on some systems it might not have file type
57 * information. On the other hand it might be faster than eina_file_stat_ls().
58 */
59/**
60 * @page eina_file_example_01
61 * @include eina_file_01.c
62 * @example eina_file_01.c
42 */ 63 */
43
44/** 64/**
45 * @addtogroup Eina_Tools_Group Tools 65 * @addtogroup Eina_Tools_Group Tools
46 * 66 *
47 * @{ 67 * @{
48 */ 68 */
49
50/** 69/**
51 * @defgroup Eina_File_Group File 70 * @addtogroup Eina_File_Group File
71 *
72 * @brief Functions to handle files and directories.
73 *
74 * This functions make it easier to do a number o file and directory operations
75 * such as getting the list of files in a directory, spliting paths and finding
76 * out file size and type.
77 *
78 * @warning All functions in this group are @b blocking which means they make
79 * take a long time to return, use them carefully.
80 *
81 * See an example @ref eina_file_example_01_page "here".
52 * 82 *
53 * @{ 83 * @{
54 */ 84 */
@@ -134,10 +164,11 @@ struct _Eina_File_Direct_Info
134 * @param data The data to pass to the callback. 164 * @param data The data to pass to the callback.
135 * @return #EINA_TRUE on success, #EINA_FALSE otherwise. 165 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
136 * 166 *
137 * This function lists all the files in @p dir. To list also all the 167 * This function calls @p cb for each file that is in @p dir. To have @p cb
138 * sub directoris recursively, @p recursive must be set to #EINA_TRUE, 168 * called on files that are in subdirectories of @p dir @p recursive should be
139 * otherwise it must be set to #EINA_FALSE. For each found file, @p cb 169 * EINA_TRUE. In other words if @p recursive is EINA_FALSE, only direct children
140 * is called and @p data is passed to it. 170 * of @p dir will be operated on, if @p recursive is EINA_TRUE the entire tree
171 * of files that is below @p dir will be operated on.
141 * 172 *
142 * If @p cb or @p dir are @c NULL, or if @p dir is a string of size 0, 173 * If @p cb or @p dir are @c NULL, or if @p dir is a string of size 0,
143 * or if @p dir can not be opened, this function returns #EINA_FALSE 174 * or if @p dir can not be opened, this function returns #EINA_FALSE
@@ -156,93 +187,87 @@ EAPI Eina_Bool eina_file_dir_list(const char *dir,
156 * 187 *
157 * This function splits @p path according to the delimiter of the used 188 * This function splits @p path according to the delimiter of the used
158 * filesystem. If @p path is @c NULL or if the array can not be 189 * filesystem. If @p path is @c NULL or if the array can not be
159 * created, @c NULL is returned, otherwise, an array with the 190 * created, @c NULL is returned, otherwise, an array with each part of @p path
160 * different parts of @p path is returned. 191 * is returned.
161 */ 192 */
162EAPI Eina_Array *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; 193EAPI Eina_Array *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
163 194
164/** 195/**
165 * Get an iterator to list the content of a directory. 196 * @brief Get an iterator to list the content of a directory.
166 *
167 * Iterators are cheap to be created and allow interruption at any
168 * iteration. At each iteration, only the next directory entry is read
169 * from the filesystem with readdir_r().
170 *
171 * The iterator will handle the user a stringshared value with the
172 * full path. One must call eina_stringshare_del() on it after usage
173 * to not leak!
174 * 197 *
175 * The eina_file_direct_ls() function will provide a possibly faster 198 * @param dir The name of the directory to list
176 * alternative if you need to filter the results somehow, like 199 * @return Return an Eina_Iterator that will walk over the files and directories
177 * checking extension. 200 * in @p dir. On failure it will return NULL.
178 * 201 *
179 * The iterator will walk over '.' and '..' without returning them. 202 * Returns an iterator for shared strings, the name of each file in @p dir will
203 * only be fetched when advancing the iterator, which means there is very little
204 * cost associated with creating the list and stopping halfway through it.
180 * 205 *
181 * The iterator container is the DIR* corresponding to the current walk. 206 * @warning The iterator will hand the user a stringshared value with the full
207 * path. The user must free the string using eina_stringshare_del() on it.
182 * 208 *
183 * @param dir The name of the directory to list 209 * @note The container for the iterator is of type DIR*.
184 * @return Return an Eina_Iterator that will walk over the files and 210 * @note The iterator will walk over '.' and '..' without returning them.
185 * directory in the pointed directory. On failure it will
186 * return NULL. The iterator emits stringshared value with the
187 * full path and must be freed with eina_stringshare_del().
188 * 211 *
189 * @see eina_file_direct_ls() 212 * @see eina_file_direct_ls()
190 */ 213 */
191EAPI Eina_Iterator *eina_file_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; 214EAPI Eina_Iterator *eina_file_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
192 215
193/** 216/**
194 * Get an iterator to list the content of a directory, with direct information. 217 * @brief Get an iterator to list the content of a directory, with direct
218 * information.
195 * 219 *
196 * Iterators are cheap to be created and allow interruption at any 220 * @param dir The name of the directory to list
197 * iteration. At each iteration, only the next directory entry is read
198 * from the filesystem with readdir_r().
199 * 221 *
200 * The iterator returns the direct pointer to couple of useful information in 222 * @return Return an Eina_Iterator that will walk over the files and
201 * #Eina_File_Direct_Info and that pointer should not be modified anyhow! 223 * directory in the pointed directory. On failure it will
224 * return NULL.
202 * 225 *
203 * The iterator will walk over '.' and '..' without returning them. 226 * Returns an iterator for Eina_File_Direct_Info, the name of each file in @p
227 * dir will only be fetched when advancing the iterator, which means there is
228 * cost associated with creating the list and stopping halfway through it.
204 * 229 *
205 * The iterator container is the DIR* corresponding to the current walk. 230 * @warning The Eina_File_Direct_Info returned by the iterator <b>must not</b>
231 * be modified in any way.
232 * @warning When the iterator is advanced or deleted the Eina_File_Direct_Info
233 * returned is no longer valid.
206 * 234 *
207 * @param dir The name of the directory to list 235 * @note The container for the iterator is of type DIR*.
208 * 236 * @note The iterator will walk over '.' and '..' without returning them.
209 * @return Return an Eina_Iterator that will walk over the files and 237 * @note The difference between this function ahd eina_file_direct_ls() is that
210 * directory in the pointed directory. On failure it will 238 * it guarantees the file type information will be correct incurring a
211 * return NULL. The iterator emits #Eina_File_Direct_Info 239 * possible performance penalty.
212 * pointers that could be used but not modified. The lifetime
213 * of the returned pointer is until the next iteration and
214 * while the iterator is live, deleting the iterator
215 * invalidates the pointer. It will call stat() when filesystem
216 * doesn't provide information to fill type from readdir_r().
217 * 240 *
218 * @see eina_file_direct_ls() 241 * @see eina_file_direct_ls()
219 */ 242 */
220EAPI Eina_Iterator *eina_file_stat_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; 243EAPI Eina_Iterator *eina_file_stat_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
221 244
222/** 245/**
223 * Get an iterator to list the content of a directory, with direct information. 246 * @brief Get an iterator to list the content of a directory, with direct
247 * information.
224 * 248 *
225 * Iterators are cheap to be created and allow interruption at any 249 * @param dir The name of the directory to list
226 * iteration. At each iteration, only the next directory entry is read
227 * from the filesystem with readdir_r().
228 * 250 *
229 * The iterator returns the direct pointer to couple of useful information in 251 * @return Return an Eina_Iterator that will walk over the files and
230 * #Eina_File_Direct_Info and that pointer should not be modified anyhow! 252 * directory in the pointed directory. On failure it will
253 * return NULL.
231 * 254 *
232 * The iterator will walk over '.' and '..' without returning them. 255 * Returns an iterator for Eina_File_Direct_Info, the name of each file in @p
256 * dir will only be fetched when advancing the iterator, which means there is
257 * cost associated with creating the list and stopping halfway through it.
233 * 258 *
234 * The iterator container is the DIR* corresponding to the current walk. 259 * @warning If readdir_r doesn't contain file type information file type will
260 * be DT_UNKNOW.
261 * @warning The Eina_File_Direct_Info returned by the iterator <b>must not</b>
262 * be modified in any way.
263 * @warning When the iterator is advanced or deleted the Eina_File_Direct_Info
264 * returned is no longer valid.
235 * 265 *
236 * @param dir The name of the directory to list 266 * @note The container for the iterator is of type DIR*.
237 * 267 * @note The iterator will walk over '.' and '..' without returning them.
238 * @return Return an Eina_Iterator that will walk over the files and 268 * @note The difference between this function ahd eina_file_stat_ls() is that
239 * directory in the pointed directory. On failure it will 269 * it may not get the file type information however it is likely to be
240 * return NULL. The iterator emits #Eina_File_Direct_Info 270 * faster.
241 * pointers that could be used but not modified. The lifetime
242 * of the returned pointer is until the next iteration and
243 * while the iterator is live, deleting the iterator
244 * invalidates the pointer. It will not call stat() when filesystem
245 * doesn't provide information to fill type from readdir_r().
246 * 271 *
247 * @see eina_file_ls() 272 * @see eina_file_ls()
248 */ 273 */
@@ -254,9 +279,9 @@ EAPI Eina_Iterator *eina_file_direct_ls(const char *dir) EINA_WARN_UNUSED_RESULT
254 * @param name Filename to open 279 * @param name Filename to open
255 * @param shared Requested a shm 280 * @param shared Requested a shm
256 * 281 *
257 * The file are only open in read only mode. Name should be an absolute path to 282 * Opens a file in read-only mode. @p name should be an absolute path. An
258 * prevent cache mistake. A handler could be shared among multiple instance and 283 * Eina_File handle can be shared among multiple instances if @p shared is
259 * will be correctly refcounted. File are automatically closed on exec. 284 * EINA_TRUE.
260 * 285 *
261 * @since 1.1 286 * @since 1.1
262 */ 287 */
@@ -267,7 +292,7 @@ EAPI Eina_File *eina_file_open(const char *name, Eina_Bool shared) EINA_WARN_UNU
267 * 292 *
268 * @param file File handler to unref. 293 * @param file File handler to unref.
269 * 294 *
270 * This doesn't close the file, it will remain open until it leave the cache. 295 * Decremente file's refcount and if it reaches zero close it.
271 * 296 *
272 * @since 1.1 297 * @since 1.1
273 */ 298 */