From dacf71345dfa3a363b511966305873f3933c73ca Mon Sep 17 00:00:00 2001 From: gastal Date: Wed, 22 Jun 2011 19:25:44 +0000 Subject: [PATCH] Eina: Eina file documentation. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/eina@60604 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- src/examples/eina_file_01.c | 45 +++++++++++ src/include/eina_file.h | 177 +++++++++++++++++++++++++------------------- 2 files changed, 146 insertions(+), 76 deletions(-) create mode 100644 src/examples/eina_file_01.c diff --git a/src/examples/eina_file_01.c b/src/examples/eina_file_01.c new file mode 100644 index 0000000..6490b62 --- /dev/null +++ b/src/examples/eina_file_01.c @@ -0,0 +1,45 @@ +//Compile with: +//gcc -g `pkg-config --cflags --libs eina` eina_file_01.c -o eina_file_01 + +#include +#include + +static void +_print_cb(const char *name, const char *path, void *data) +{ + printf("file %s in %s\n", name, path); +} + +int +main(int argc, char **argv) +{ + Eina_Iterator *it; + const char *f_name; + const Eina_File_Direct_Info *f_info; + + eina_init(); + + eina_file_dir_list("/home/", EINA_FALSE, _print_cb, NULL); + + it = eina_file_ls("/home/"); + EINA_ITERATOR_FOREACH(it, f_name) + { + printf("%s\n", f_name); + eina_stringshare_del(f_name); + } + eina_iterator_free(it); + + it = eina_file_stat_ls("/home/"); + EINA_ITERATOR_FOREACH(it, f_info) + printf("%s if of type %d\n", f_info->path, f_info->type); + eina_iterator_free(it); + + it = eina_file_direct_ls("/home/"); + EINA_ITERATOR_FOREACH(it, f_info) + printf("%s if of type %d\n", f_info->path, f_info->type); + eina_iterator_free(it); + + eina_shutdown(); + + return 0; +} diff --git a/src/include/eina_file.h b/src/include/eina_file.h index a75ddac..e02e501 100644 --- a/src/include/eina_file.h +++ b/src/include/eina_file.h @@ -28,27 +28,57 @@ /** - * @addtogroup Eina_File_Group File + * @page eina_file_example_01_page + * @dontinclude eina_file_01.c * - * @brief Functions to traverse directories and split paths. + * For brevity includes, variable declarations and initialization was ommited + * from this page, however the full source code can be seen @ref + * eina_file_example_01 "here". * - * @li eina_file_dir_list() list the content of a directory, - * recusrsively or not, and can call a callback function for eachfound - * file. - * @li eina_file_split() split a path into all the subdirectories that - * compose it, according to the separator of the file system. + * Here we have a simple callback to print the name of a file and the path that + * contains it: + * @skip static + * @until } * - * @{ + * We can use this callback in the following call: + * @skipline eina_file_dir_list + * + * The above was a way to print the files in a directory, but it is not the only + * one: + * @until iterator_free + * + * And now two ways to get more information than just file names: + * @until iterator_free + * @until iterator_free + * + * The above ways of getting files on a list may produce the same output, but + * they have an important difference, eina_file_direct_ls() will @b not call + * stat, this means that on some systems it might not have file type + * information. On the other hand it might be faster than eina_file_stat_ls(). + */ +/** + * @page eina_file_example_01 + * @include eina_file_01.c + * @example eina_file_01.c */ - /** * @addtogroup Eina_Tools_Group Tools * * @{ */ - /** - * @defgroup Eina_File_Group File + * @addtogroup Eina_File_Group File + * + * @brief Functions to handle files and directories. + * + * This functions make it easier to do a number o file and directory operations + * such as getting the list of files in a directory, spliting paths and finding + * out file size and type. + * + * @warning All functions in this group are @b blocking which means they make + * take a long time to return, use them carefully. + * + * See an example @ref eina_file_example_01_page "here". * * @{ */ @@ -134,10 +164,11 @@ struct _Eina_File_Direct_Info * @param data The data to pass to the callback. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * - * This function lists all the files in @p dir. To list also all the - * sub directoris recursively, @p recursive must be set to #EINA_TRUE, - * otherwise it must be set to #EINA_FALSE. For each found file, @p cb - * is called and @p data is passed to it. + * This function calls @p cb for each file that is in @p dir. To have @p cb + * called on files that are in subdirectories of @p dir @p recursive should be + * EINA_TRUE. In other words if @p recursive is EINA_FALSE, only direct children + * of @p dir will be operated on, if @p recursive is EINA_TRUE the entire tree + * of files that is below @p dir will be operated on. * * If @p cb or @p dir are @c NULL, or if @p dir is a string of size 0, * 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, * * This function splits @p path according to the delimiter of the used * filesystem. If @p path is @c NULL or if the array can not be - * created, @c NULL is returned, otherwise, an array with the - * different parts of @p path is returned. + * created, @c NULL is returned, otherwise, an array with each part of @p path + * is returned. */ EAPI Eina_Array *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; /** - * Get an iterator to list the content of a directory. - * - * Iterators are cheap to be created and allow interruption at any - * iteration. At each iteration, only the next directory entry is read - * from the filesystem with readdir_r(). - * - * The iterator will handle the user a stringshared value with the - * full path. One must call eina_stringshare_del() on it after usage - * to not leak! + * @brief Get an iterator to list the content of a directory. * - * The eina_file_direct_ls() function will provide a possibly faster - * alternative if you need to filter the results somehow, like - * checking extension. + * @param dir The name of the directory to list + * @return Return an Eina_Iterator that will walk over the files and directories + * in @p dir. On failure it will return NULL. * - * The iterator will walk over '.' and '..' without returning them. + * Returns an iterator for shared strings, the name of each file in @p dir will + * only be fetched when advancing the iterator, which means there is very little + * cost associated with creating the list and stopping halfway through it. * - * The iterator container is the DIR* corresponding to the current walk. + * @warning The iterator will hand the user a stringshared value with the full + * path. The user must free the string using eina_stringshare_del() on it. * - * @param dir The name of the directory to list - * @return Return an Eina_Iterator that will walk over the files and - * directory in the pointed directory. On failure it will - * return NULL. The iterator emits stringshared value with the - * full path and must be freed with eina_stringshare_del(). + * @note The container for the iterator is of type DIR*. + * @note The iterator will walk over '.' and '..' without returning them. * * @see eina_file_direct_ls() */ EAPI Eina_Iterator *eina_file_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; /** - * Get an iterator to list the content of a directory, with direct information. + * @brief Get an iterator to list the content of a directory, with direct + * information. * - * Iterators are cheap to be created and allow interruption at any - * iteration. At each iteration, only the next directory entry is read - * from the filesystem with readdir_r(). + * @param dir The name of the directory to list * - * The iterator returns the direct pointer to couple of useful information in - * #Eina_File_Direct_Info and that pointer should not be modified anyhow! + * @return Return an Eina_Iterator that will walk over the files and + * directory in the pointed directory. On failure it will + * return NULL. * - * The iterator will walk over '.' and '..' without returning them. + * Returns an iterator for Eina_File_Direct_Info, the name of each file in @p + * dir will only be fetched when advancing the iterator, which means there is + * cost associated with creating the list and stopping halfway through it. * - * The iterator container is the DIR* corresponding to the current walk. + * @warning The Eina_File_Direct_Info returned by the iterator must not + * be modified in any way. + * @warning When the iterator is advanced or deleted the Eina_File_Direct_Info + * returned is no longer valid. * - * @param dir The name of the directory to list - * - * @return Return an Eina_Iterator that will walk over the files and - * directory in the pointed directory. On failure it will - * return NULL. The iterator emits #Eina_File_Direct_Info - * pointers that could be used but not modified. The lifetime - * of the returned pointer is until the next iteration and - * while the iterator is live, deleting the iterator - * invalidates the pointer. It will call stat() when filesystem - * doesn't provide information to fill type from readdir_r(). + * @note The container for the iterator is of type DIR*. + * @note The iterator will walk over '.' and '..' without returning them. + * @note The difference between this function ahd eina_file_direct_ls() is that + * it guarantees the file type information will be correct incurring a + * possible performance penalty. * * @see eina_file_direct_ls() */ EAPI Eina_Iterator *eina_file_stat_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; /** - * Get an iterator to list the content of a directory, with direct information. + * @brief Get an iterator to list the content of a directory, with direct + * information. * - * Iterators are cheap to be created and allow interruption at any - * iteration. At each iteration, only the next directory entry is read - * from the filesystem with readdir_r(). + * @param dir The name of the directory to list * - * The iterator returns the direct pointer to couple of useful information in - * #Eina_File_Direct_Info and that pointer should not be modified anyhow! + * @return Return an Eina_Iterator that will walk over the files and + * directory in the pointed directory. On failure it will + * return NULL. * - * The iterator will walk over '.' and '..' without returning them. + * Returns an iterator for Eina_File_Direct_Info, the name of each file in @p + * dir will only be fetched when advancing the iterator, which means there is + * cost associated with creating the list and stopping halfway through it. * - * The iterator container is the DIR* corresponding to the current walk. + * @warning If readdir_r doesn't contain file type information file type will + * be DT_UNKNOW. + * @warning The Eina_File_Direct_Info returned by the iterator must not + * be modified in any way. + * @warning When the iterator is advanced or deleted the Eina_File_Direct_Info + * returned is no longer valid. * - * @param dir The name of the directory to list - * - * @return Return an Eina_Iterator that will walk over the files and - * directory in the pointed directory. On failure it will - * return NULL. The iterator emits #Eina_File_Direct_Info - * pointers that could be used but not modified. The lifetime - * of the returned pointer is until the next iteration and - * while the iterator is live, deleting the iterator - * invalidates the pointer. It will not call stat() when filesystem - * doesn't provide information to fill type from readdir_r(). + * @note The container for the iterator is of type DIR*. + * @note The iterator will walk over '.' and '..' without returning them. + * @note The difference between this function ahd eina_file_stat_ls() is that + * it may not get the file type information however it is likely to be + * faster. * * @see eina_file_ls() */ @@ -254,9 +279,9 @@ EAPI Eina_Iterator *eina_file_direct_ls(const char *dir) EINA_WARN_UNUSED_RESULT * @param name Filename to open * @param shared Requested a shm * - * The file are only open in read only mode. Name should be an absolute path to - * prevent cache mistake. A handler could be shared among multiple instance and - * will be correctly refcounted. File are automatically closed on exec. + * Opens a file in read-only mode. @p name should be an absolute path. An + * Eina_File handle can be shared among multiple instances if @p shared is + * EINA_TRUE. * * @since 1.1 */ @@ -267,7 +292,7 @@ EAPI Eina_File *eina_file_open(const char *name, Eina_Bool shared) EINA_WARN_UNU * * @param file File handler to unref. * - * This doesn't close the file, it will remain open until it leave the cache. + * Decremente file's refcount and if it reaches zero close it. * * @since 1.1 */ -- 2.7.4