aboutsummaryrefslogtreecommitdiffstats
path: root/legacy/ecore/src/lib/ecore_file/ecore_file.c
diff options
context:
space:
mode:
authorVincent Torri <vincent.torri@gmail.com>2010-10-23 11:05:36 +0000
committerVincent Torri <vincent.torri@gmail.com>2010-10-23 11:05:36 +0000
commit259b702319a5cfe8edd2be88b1d8fa7cbea0848e (patch)
treea7afcffc1bbe922e33d95aad90464e50a86339bf /legacy/ecore/src/lib/ecore_file/ecore_file.c
parentwindows mutex shutdown correctness++ (diff)
downloadefl-259b702319a5cfe8edd2be88b1d8fa7cbea0848e.tar.gz
[ecore-file] fix doc
SVN revision: 53810
Diffstat (limited to '')
-rw-r--r--legacy/ecore/src/lib/ecore_file/ecore_file.c373
1 files changed, 267 insertions, 106 deletions
diff --git a/legacy/ecore/src/lib/ecore_file/ecore_file.c b/legacy/ecore/src/lib/ecore_file/ecore_file.c
index 6b69edd02f..b568ca2d6e 100644
--- a/legacy/ecore/src/lib/ecore_file/ecore_file.c
+++ b/legacy/ecore/src/lib/ecore_file/ecore_file.c
@@ -26,11 +26,25 @@ int _ecore_file_log_dom = -1;
static int _ecore_file_init_count = 0;
/* externally accessible functions */
+
+/**
+ * @addtogroup Ecore_File_Group Ecore_File - Files and direcotries convenience functions
+ *
+ * @{
+ */
+
/**
- * Initialize Ecore_File and the services it will use. Call this function
- * once before you use any of the ecore file functions.
- * @return Number of times ecore_file_init() was called successfully or 0 if
- * this call failed.
+ * @brief Initialize the Ecore_File library.
+ *
+ * @return 1 or greater on success, 0 on error.
+ *
+ * This function sets up Ecore_File and the services it will use
+ * (monitoring, downloading, PATH related feature). It returns 0 on
+ * failure, otherwise it returns the number of times it has already
+ * been called.
+ *
+ * When Ecore_File is not used anymore, call ecore_file_shutdown()
+ * to shut down the Ecore_File library.
*/
EAPI int
ecore_file_init()
@@ -71,8 +85,14 @@ ecore_file_init()
}
/**
- * Shutdown the Ecore_File
- * @return returns the number of libraries that still uses Ecore_File
+ * @brief Shut down the Ecore_File library.
+ *
+ * @return 0 when the library is completely shut down, 1 or
+ * greater otherwise.
+ *
+ * This function shuts down the Ecore_File library. It returns 0 when it has
+ * been called the same number of times than ecore_file_init(). In that case
+ * it shuts down all the services it uses.
*/
EAPI int
ecore_file_shutdown()
@@ -89,10 +109,14 @@ ecore_file_shutdown()
}
/**
- * Get the time of the last modification to the give file
- * @param file The name of the file
- * @return Return the time of the last data modification, if an error should
- * occur it will return 0
+ * @brief Get the time of the last modification to the given file.
+ *
+ * @param file The name of the file.
+ * @return Return the time of the last data modification, or 0 on
+ * failure.
+ *
+ * This function returns the time of the last modification of
+ * @p file. On failure, it returns 0.
*/
EAPI long long
ecore_file_mod_time(const char *file)
@@ -104,9 +128,13 @@ ecore_file_mod_time(const char *file)
}
/**
- * Get the size of the given file
- * @param file The name of the file
- * @return The size of the file in byte
+ * @brief Get the size of the given file.
+ *
+ * @param file The name of the file.
+ * @return Return the size of the file in bytes, or 0 on failure.
+ *
+ * This function returns the size of @p file in bytes. On failure, it
+ * returns 0.
*/
EAPI long long
ecore_file_size(const char *file)
@@ -118,9 +146,13 @@ ecore_file_size(const char *file)
}
/**
- * Check if file exists
- * @param file The name of the file
- * @return EINA_TRUE if file exists on local filesystem, EINA_FALSE otherwise
+ * @brief Check if the given file exists.
+ *
+ * @param file The name of the file.
+ * @return Return EINA_TRUE if the file exists, EINA_FALSE otherwise.
+ *
+ * This function returns EINA_TRUE if @p file exists on local filesystem,
+ * EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_exists(const char *file)
@@ -133,9 +165,14 @@ ecore_file_exists(const char *file)
}
/**
- * Check if file is a directory
- * @param file The name of the file
- * @return EINA_TRUE if file exist and is a directory, EINA_FALSE otherwise
+ * @brief Check if the given file is a directory.
+ *
+ * @param file The name of the file.
+ * @return Return EINA_TRUE if the file exists and is a directory,
+ * EINA_FALSE otherwise.
+ *
+ * This function returns EINA_TRUE if @p file exists exists and is a
+ * directory on local filesystem, EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_is_dir(const char *file)
@@ -150,11 +187,14 @@ ecore_file_is_dir(const char *file)
static mode_t default_mode = S_IRUSR | S_IWUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH;
/**
- * Create a new directory
+ * @brief Create a new directory.
+ *
* @param dir The name of the directory to create
- * @return EINA_TRUE on successful creation, EINA_FALSE on failure
+ * @return EINA_TRUE on successful creation, EINA_FALSE otherwise.
*
- * The directory is created with the mode: S_IRUSR | S_IWUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH
+ * This function creates the directory @p dir with the mode S_IRUSR |
+ * S_IWUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH. On
+ * success, it returns EINA_TRUE, EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_mkdir(const char *dir)
@@ -164,12 +204,17 @@ ecore_file_mkdir(const char *dir)
}
/**
- * Create complete directory in a batch.
+ * @brief Create complete directory in a batch.
*
- * @param dirs list of directories, null terminated.
- * @return number of successful directories created, -1 if dirs is NULL.
+ * @param dirs The list of directories, null terminated.
+ * @return The number of successful directories created, -1 if dirs is
+ * @c NULL.
*
- * @see ecore_file_mkdir() and ecore_file_mkpaths()
+ * This function creates all the directories that are in the null
+ * terminated array @p dirs. The function loops over the directories
+ * and call ecore_file_mkdir(). This function returns -1 if @p dirs is
+ * @c NULL, otherwise if returns the number of suceesfully created
+ * directories.
*/
EAPI int
ecore_file_mkdirs(const char **dirs)
@@ -185,19 +230,22 @@ ecore_file_mkdirs(const char **dirs)
}
/**
- * Create complete list of sub-directories in a batch (optimized).
- *
- * @param base the base directory to act on, will be created if does
- * not exists.
- * @param subdirs list of directories, null terminated. These are
- * created similarly to ecore_file_mkdir(), so same mode and whole
- * path to that point must exists. So if creating base/a/b/c,
- * provide subdirs with "a", "a/b" and "a/b/c" in that order!
+ * @brief Create complete list of sub-directories in a batch (optimized).
*
- * @return number of successful directories created, -1 if subdirs or
- * base is NULL or invalid.
+ * @param base The base directory to act on.
+ * @param subdirs The list of directories, null terminated.
+ * @return number of successful directories created, -1 on failure.
*
- * @see ecore_file_mkdir() and ecore_file_mkpaths()
+ * This function creates all the directories that are in the null
+ * terminated array @p dirs in the @p base directory. If @p base does
+ * not exist, it will be created. The function loops over the directories
+ * and call ecore_file_mkdir(). The whole path of the directories must
+ * exist. So if base/a/b/c wants to be created, @p subdirs must
+ * contain "a", "a/b" and "a/b/c", in that order. This function
+ * returns -1 if @p dirs or @p base are @c NULL, or if @p base is
+ * empty ("\0"). It returns 0 is @p base is not a directory or
+ * invalid, or if it can't be created. Otherwise if returns the number
+ * of suceesfully created directories.
*/
EAPI int
ecore_file_mksubdirs(const char *base, const char **subdirs)
@@ -277,9 +325,13 @@ ecore_file_mksubdirs(const char *base, const char **subdirs)
}
/**
- * Delete the given dir
- * @param dir The name of the directory to delete
- * @return EINA_TRUE on success, EINA_FALSE on failure
+ * @brief Delete the given directory.
+ *
+ * @param dir The name of the directory to delete.
+ * @return EINA_TRUE on success, EINA_FALSE otherwise.
+ *
+ * This function deletes @p dir. It returns EINA_TRUE on success,
+ * EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_rmdir(const char *dir)
@@ -289,9 +341,13 @@ ecore_file_rmdir(const char *dir)
}
/**
- * Delete the given file
- * @param file The name of the file to delete
- * @return EINA_TRUE on success, EINA_FALSE on failure
+ * @brief Delete the given file.
+ *
+ * @param file The name of the file to delete.
+ * @return EINA_TRUE on success, EINA_FALSE otherwise.
+ *
+ * This function deletes @p file. It returns EINA_TRUE on success,
+ * EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_unlink(const char *file)
@@ -301,9 +357,13 @@ ecore_file_unlink(const char *file)
}
/**
- * Remove the given file or directory
- * @param file The name of the file or directory to delete
- * @return EINA_TRUE on success, EINA_FALSE on failure
+ * @brief Remove the given file or directory.
+ *
+ * @param file The name of the file or directory to delete.
+ * @return EINA_TRUE on success, EINA_FALSE otherwise.
+ *
+ * This function removes @p file. It returns EINA_TRUE on success,
+ * EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_remove(const char *file)
@@ -313,11 +373,14 @@ ecore_file_remove(const char *file)
}
/**
- * Delete a directory and all its contents
- * @param dir The name of the directory to delete
- * @return EINA_TRUE on success, EINA_FALSE on failure
+ * @brief Delete the given directory and all its contents.
*
- * If dir is a link only the link is removed
+ * @param dir The name of the directory to delete.
+ * @return EINA_TRUE on success, EINA_FALSE otherwise.
+ *
+ * This function delete @p dir and all its contents. If @p dir is a
+ * link only the link is removed. It returns EINA_TRUE on success,
+ * EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_recursive_rm(const char *dir)
@@ -377,11 +440,15 @@ _ecore_file_mkpath_if_not_exists(const char *path)
}
/**
- * Create a complete path
+ * @brief Create a complete path.
+ *
* @param path The path to create
- * @return EINA_TRUE on success, EINA_FALSE on failure
+ * @return EINA_TRUE on success, EINA_FALSE otherwise.
*
- * @see ecore_file_mkpaths() and ecore_file_mkdir()
+ * This function create @p path and all the subdirectories it
+ * contains. The separator is '/' so, on Windows, '\' must be replaced
+ * by '/'. If @p path exists, this function returns EINA_TRUE
+ * immediatly. It returns EINA_TRUE on success, EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_mkpath(const char *path)
@@ -407,12 +474,17 @@ ecore_file_mkpath(const char *path)
}
/**
- * Create complete paths in a batch.
+ * @brief Create complete paths in a batch.
*
* @param paths list of paths, null terminated.
* @return number of successful paths created, -1 if paths is NULL.
*
- * @see ecore_file_mkpath() and ecore_file_mkdirs()
+ * This function creates all the directories that are in the null
+ * terminated array @p paths. The function loops over the directories
+ * and call ecore_file_mkpath(), hence on Windows, '\' must be
+ * replaced by '/' before calling that function. This function
+ * returns -1 if @p paths is @c NULL. Otherwise if returns the number
+ * of suceesfully created directories.
*/
EAPI int
ecore_file_mkpaths(const char **paths)
@@ -428,10 +500,16 @@ ecore_file_mkpaths(const char **paths)
}
/**
- * Copy a file
- * @param src The name of the source file
- * @param dst The name of the destination file
- * @return EINA_TRUE on success, EINA_FALSE on failure
+ * @brief Copy the given file to the given destination.
+ *
+ * @param src The name of the source file.
+ * @param dst The name of the destination file.
+ * @return EINA_TRUE on success, EINA_FALSE otherwise.
+ *
+ * This function copies @p src to @p dst. If the absolute path name of
+ * @p src and @p dst can not be computed, or if they are equal, or if
+ * the copy fails, the function returns EINA_FALSE, otherwise it
+ * returns EINA_TRUE.
*/
EAPI Eina_Bool
ecore_file_cp(const char *src, const char *dst)
@@ -463,10 +541,14 @@ ecore_file_cp(const char *src, const char *dst)
}
/**
- * Move a file
- * @param src The name of the source file
- * @param dst The name of the destination file
- * @return EINA_TRUE on success, EINA_FALSE on failure
+ * @brief Move the given file to the given destination.
+ *
+ * @param src The name of the source file.
+ * @param dst The name of the destination file.
+ * @return EINA_TRUE on success, EINA_FALSE otherwise.
+ *
+ * This function moves @p src to @p dst. It returns EINA_TRUE on
+ * success, EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_mv(const char *src, const char *dst)
@@ -537,10 +619,15 @@ FAIL:
}
/**
- * Create a symbolic link
- * @param src The name of the file to link
- * @param dest The name of link
- * @return EINA_TRUE on success, EINA_FALSE on failure
+ * @brief Create a symbolic link.
+ *
+ * @param src The name of the file to link.
+ * @param dest The name of link.
+ * @return EINA_TRUE on success, EINA_FALSE otherwise.
+ *
+ * This function create the symbolic link @p dest of @p src. This
+ * function does not work on Windows. It returns EINA_TRUE on success,
+ * EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_symlink(const char *src, const char *dest)
@@ -551,10 +638,16 @@ ecore_file_symlink(const char *src, const char *dest)
}
/**
- * Get the canonicalized absolute pathname
- * @param file The file path
- * @return The canonicalized absolute pathname; on failure it will return
- * an empty string
+ * @brief Get the canonicalized absolute path name.
+ *
+ * @param file The file path.
+ * @return The canonicalized absolute pathname or an empty string on
+ * failure.
+ *
+ * This function returns the absolute path name of @p file as a newly
+ * allocated string. If @p file is @c NULL, or on error, this function
+ * returns an empty string. Otherwise, it returns the absolute path
+ * name. When not needed anymore, the returned value must be freed.
*/
EAPI char *
ecore_file_realpath(const char *file)
@@ -572,9 +665,13 @@ ecore_file_realpath(const char *file)
}
/**
- * Get the filename from a give path
- * @param path The complete path
- * @return Only the file name
+ * Get the filename from a given path.
+ *
+ * @param path The complete path.
+ * @return The file name.
+ *
+ * This function returns the file name of @p path. If @p path is
+ * @c NULL, the functions returns @c NULL.
*/
EAPI const char *
ecore_file_file_get(const char *path)
@@ -588,9 +685,15 @@ ecore_file_file_get(const char *path)
}
/**
- * Get the directory where file reside
- * @param file The name of the file
- * @return The directory name
+ * @brief Get the directory where the given file resides.
+ *
+ * @param file The name of the file.
+ * @return The directory name.
+ *
+ * This function returns the directory where @p file resides as anewly
+ * allocated string. If @p file is @c NULL or on error, this function
+ * returns @c NULL. When not needed anymore, the returned value must
+ * be freed.
*/
EAPI char *
ecore_file_dir_get(const char *file)
@@ -606,9 +709,13 @@ ecore_file_dir_get(const char *file)
}
/**
- * Check if file can be read
- * @param file The name of the file
- * @return EINA_TRUE if the file is readable, EINA_FALSE otherwise
+ * @brief Check if the given file can be read.
+ *
+ * @param file The name of the file.
+ * @return EINA_TRUE if the file is readable, EINA_FALSE otherwise.
+ *
+ * This function returns EINA_TRUE if @p file can be read, EINA_FALSE
+ * otherwise.
*/
EAPI Eina_Bool
ecore_file_can_read(const char *file)
@@ -619,9 +726,13 @@ ecore_file_can_read(const char *file)
}
/**
- * Check if file can be written
- * @param file The name of the file
- * @return EINA_TRUE if the file is writable, EINA_FALSE otherwise
+ * @brief Check if the given file can be written.
+ *
+ * @param file The name of the file.
+ * @return EINA_TRUE if the file is writable, EINA_FALSE otherwise.
+ *
+ * This function returns EINA_TRUE if @p file can be written, EINA_FALSE
+ * otherwise.
*/
EAPI Eina_Bool
ecore_file_can_write(const char *file)
@@ -632,9 +743,13 @@ ecore_file_can_write(const char *file)
}
/**
- * Check if file can be executed
- * @param file The name of the file
- * @return EINA_TRUE if the file can be executed, EINA_FALSE otherwise
+ * @bbrief Check if the given file can be executed.
+ *
+ * @param file The name of the file.
+ * @return EINA_TRUE if the file can be executed, EINA_FALSE otherwise.
+ *
+ * This function returns EINA_TRUE if @p file can be executed, EINA_FALSE
+ * otherwise.
*/
EAPI Eina_Bool
ecore_file_can_exec(const char *file)
@@ -645,9 +760,15 @@ ecore_file_can_exec(const char *file)
}
/**
- * Get the path pointed by link
- * @param link The name of the link
- * @return The path pointed by link or NULL
+ * @brief Get the path pointed by the given link.
+ *
+ * @param link The name of the link.
+ * @return The path pointed by link or NULL.
+ *
+ * This function returns the path pointed by @p link as a newly
+ * allocated string. This function does not work on Windows. On
+ * failure, the function returns @c NULL. When not needed anymore, the
+ * returned value must be freed.
*/
EAPI char *
ecore_file_readlink(const char *link)
@@ -661,14 +782,21 @@ ecore_file_readlink(const char *link)
}
/**
- * Get the list of the files and directories in a given directory. The list
- * will be sorted with strcoll as compare function. That means that you may
- * want to set the current locale for the category LC_COLLATE with setlocale().
- * For more information see the manual pages of strcoll and setlocale.
- * The list will not contain the directory entries for '.' and '..'.
+ * @brief Get the list of the files and directories in the given
+ * directory.
+ *
* @param dir The name of the directory to list
* @return Return an Eina_List containing all the files in the directory;
* on failure it returns NULL.
+ *
+ * This function returns a list of allocated strings of all the files
+ * and directories contained in @p dir. The list will be sorted with
+ * strcoll as compare function. That means that you may want to set
+ * the current locale for the category LC_COLLATE with
+ * setlocale(). For more information see the manual pages of strcoll
+ * and setlocale. The list will not contain the directory entries for
+ * '.' and '..'. On failure, @c NULL is returned. When not needed
+ * anymore, the list elements must be freed.
*/
EAPI Eina_List *
ecore_file_ls(const char *dir)
@@ -697,7 +825,14 @@ ecore_file_ls(const char *dir)
}
/**
- * FIXME: To be documented.
+ * @brief Return the executable from the given command.
+ *
+ * @param app The application command, with parameters.
+ *
+ * This function returns the executable from @p app as a newly
+ * allocated string. Arguments are removed and escae characters are
+ * handled. If @p app is @c NULL, or on failure, the function returns
+ * @c NULL. When not needed anymore, the returned value must be freed.
*/
EAPI char *
ecore_file_app_exe_get(const char *app)
@@ -792,7 +927,7 @@ restart:
in_quot_dbl = 0;
else
{
- /* techcincally this is wrong. double quotes also accept
+ /* technically this is wrong. double quotes also accept
* special chars:
*
* $, `, \
@@ -845,10 +980,16 @@ restart:
}
/**
- * Add the escape sequence ('\\') to the given filename
- * @param filename The file name
- * @return The file name with special characters escaped; if the length of the
- * resulting string is longer than PATH_MAX it will return NULL
+ * @brief Add the escape sequence ('\\') to the given file name.
+ *
+ * @param filename The file name.
+ * @return The file name with special characters escaped.
+ *
+ * This function adds the escape sequence ('\\') to the given file
+ * name and returns the result as a newly allocated string. If the
+ * length of the returned string is longer than PATH_MAX, or on
+ * failure, @c NULL is returned. When not needed anymore, the returned
+ * value must be freed.
*/
EAPI char *
ecore_file_escape_name(const char *filename)
@@ -885,15 +1026,25 @@ ecore_file_escape_name(const char *filename)
}
/**
- * Remove the extension from a given path
- * @param path The name of the file
- * @return A newly allocated string with the extension stripped out or NULL on errors
+ * @bried Remove the extension from the given file name.
+ *
+ * @param path The name of the file.
+ * @return A newly allocated string with the extension stripped out or
+ * NULL on errors.
+ *
+ * This function removes the extension from @p path and returns the
+ * result as a newly allocated string. If @p path is @c NULL, or on
+ * failure, the function returns @c NULL. When not needed anymore, the
+ * returned value must be freed.
*/
EAPI char *
ecore_file_strip_ext(const char *path)
{
char *p, *file = NULL;
+ if (!path)
+ return NULL;
+
p = strrchr(path, '.');
if (!p)
file = strdup(path);
@@ -911,9 +1062,15 @@ ecore_file_strip_ext(const char *path)
}
/**
- * Check if the given directory is empty. The '.' and '..' files will be ignored.
- * @param dir The name of the directory to check
- * @return 1 if directory is empty, 0 if it has at least one file or -1 in case of errors
+ * @brief Check if the given directory is empty.
+ *
+ * @param dir The name of the directory to check.
+ * @return 1 if directory is empty, 0 if it has at least one file or
+ * -1 in case of errors.
+ *
+ * This functions checks if @p dir is empty. The '.' and '..' files
+ * will be ignored. If @p dir is empty, 1 is returned, if it contains
+ * at least 1 file, 0 is returned. On failure, -1 is returned.
*/
EAPI int
ecore_file_dir_is_empty(const char *dir)
@@ -936,3 +1093,7 @@ ecore_file_dir_is_empty(const char *dir)
closedir(dirp);
return 1;
}
+
+/**
+ * @}
+ */