diff options
author | Vincent Torri <vincent.torri@gmail.com> | 2010-10-23 11:05:36 +0000 |
---|---|---|
committer | Vincent Torri <vincent.torri@gmail.com> | 2010-10-23 11:05:36 +0000 |
commit | 259b702319a5cfe8edd2be88b1d8fa7cbea0848e (patch) | |
tree | a7afcffc1bbe922e33d95aad90464e50a86339bf /legacy/ecore/src/lib/ecore_file/ecore_file.c | |
parent | 8055b915b7585e80730b3df539a8eb73a0c5a3e8 (diff) |
[ecore-file] fix doc
SVN revision: 53810
Diffstat (limited to '')
-rw-r--r-- | legacy/ecore/src/lib/ecore_file/ecore_file.c | 373 |
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; | |||
26 | static int _ecore_file_init_count = 0; | 26 | static int _ecore_file_init_count = 0; |
27 | 27 | ||
28 | /* externally accessible functions */ | 28 | /* externally accessible functions */ |
29 | |||
30 | /** | ||
31 | * @addtogroup Ecore_File_Group Ecore_File - Files and direcotries convenience functions | ||
32 | * | ||
33 | * @{ | ||
34 | */ | ||
35 | |||
29 | /** | 36 | /** |
30 | * Initialize Ecore_File and the services it will use. Call this function | 37 | * @brief Initialize the Ecore_File library. |
31 | * once before you use any of the ecore file functions. | 38 | * |
32 | * @return Number of times ecore_file_init() was called successfully or 0 if | 39 | * @return 1 or greater on success, 0 on error. |
33 | * this call failed. | 40 | * |
41 | * This function sets up Ecore_File and the services it will use | ||
42 | * (monitoring, downloading, PATH related feature). It returns 0 on | ||
43 | * failure, otherwise it returns the number of times it has already | ||
44 | * been called. | ||
45 | * | ||
46 | * When Ecore_File is not used anymore, call ecore_file_shutdown() | ||
47 | * to shut down the Ecore_File library. | ||
34 | */ | 48 | */ |
35 | EAPI int | 49 | EAPI int |
36 | ecore_file_init() | 50 | ecore_file_init() |
@@ -71,8 +85,14 @@ ecore_file_init() | |||
71 | } | 85 | } |
72 | 86 | ||
73 | /** | 87 | /** |
74 | * Shutdown the Ecore_File | 88 | * @brief Shut down the Ecore_File library. |
75 | * @return returns the number of libraries that still uses Ecore_File | 89 | * |
90 | * @return 0 when the library is completely shut down, 1 or | ||
91 | * greater otherwise. | ||
92 | * | ||
93 | * This function shuts down the Ecore_File library. It returns 0 when it has | ||
94 | * been called the same number of times than ecore_file_init(). In that case | ||
95 | * it shuts down all the services it uses. | ||
76 | */ | 96 | */ |
77 | EAPI int | 97 | EAPI int |
78 | ecore_file_shutdown() | 98 | ecore_file_shutdown() |
@@ -89,10 +109,14 @@ ecore_file_shutdown() | |||
89 | } | 109 | } |
90 | 110 | ||
91 | /** | 111 | /** |
92 | * Get the time of the last modification to the give file | 112 | * @brief Get the time of the last modification to the given file. |
93 | * @param file The name of the file | 113 | * |
94 | * @return Return the time of the last data modification, if an error should | 114 | * @param file The name of the file. |
95 | * occur it will return 0 | 115 | * @return Return the time of the last data modification, or 0 on |
116 | * failure. | ||
117 | * | ||
118 | * This function returns the time of the last modification of | ||
119 | * @p file. On failure, it returns 0. | ||
96 | */ | 120 | */ |
97 | EAPI long long | 121 | EAPI long long |
98 | ecore_file_mod_time(const char *file) | 122 | ecore_file_mod_time(const char *file) |
@@ -104,9 +128,13 @@ ecore_file_mod_time(const char *file) | |||
104 | } | 128 | } |
105 | 129 | ||
106 | /** | 130 | /** |
107 | * Get the size of the given file | 131 | * @brief Get the size of the given file. |
108 | * @param file The name of the file | 132 | * |
109 | * @return The size of the file in byte | 133 | * @param file The name of the file. |
134 | * @return Return the size of the file in bytes, or 0 on failure. | ||
135 | * | ||
136 | * This function returns the size of @p file in bytes. On failure, it | ||
137 | * returns 0. | ||
110 | */ | 138 | */ |
111 | EAPI long long | 139 | EAPI long long |
112 | ecore_file_size(const char *file) | 140 | ecore_file_size(const char *file) |
@@ -118,9 +146,13 @@ ecore_file_size(const char *file) | |||
118 | } | 146 | } |
119 | 147 | ||
120 | /** | 148 | /** |
121 | * Check if file exists | 149 | * @brief Check if the given file exists. |
122 | * @param file The name of the file | 150 | * |
123 | * @return EINA_TRUE if file exists on local filesystem, EINA_FALSE otherwise | 151 | * @param file The name of the file. |
152 | * @return Return EINA_TRUE if the file exists, EINA_FALSE otherwise. | ||
153 | * | ||
154 | * This function returns EINA_TRUE if @p file exists on local filesystem, | ||
155 | * EINA_FALSE otherwise. | ||
124 | */ | 156 | */ |
125 | EAPI Eina_Bool | 157 | EAPI Eina_Bool |
126 | ecore_file_exists(const char *file) | 158 | ecore_file_exists(const char *file) |
@@ -133,9 +165,14 @@ ecore_file_exists(const char *file) | |||
133 | } | 165 | } |
134 | 166 | ||
135 | /** | 167 | /** |
136 | * Check if file is a directory | 168 | * @brief Check if the given file is a directory. |
137 | * @param file The name of the file | 169 | * |
138 | * @return EINA_TRUE if file exist and is a directory, EINA_FALSE otherwise | 170 | * @param file The name of the file. |
171 | * @return Return EINA_TRUE if the file exists and is a directory, | ||
172 | * EINA_FALSE otherwise. | ||
173 | * | ||
174 | * This function returns EINA_TRUE if @p file exists exists and is a | ||
175 | * directory on local filesystem, EINA_FALSE otherwise. | ||
139 | */ | 176 | */ |
140 | EAPI Eina_Bool | 177 | EAPI Eina_Bool |
141 | ecore_file_is_dir(const char *file) | 178 | ecore_file_is_dir(const char *file) |
@@ -150,11 +187,14 @@ ecore_file_is_dir(const char *file) | |||
150 | static mode_t default_mode = S_IRUSR | S_IWUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH; | 187 | static mode_t default_mode = S_IRUSR | S_IWUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH; |
151 | 188 | ||
152 | /** | 189 | /** |
153 | * Create a new directory | 190 | * @brief Create a new directory. |
191 | * | ||
154 | * @param dir The name of the directory to create | 192 | * @param dir The name of the directory to create |
155 | * @return EINA_TRUE on successful creation, EINA_FALSE on failure | 193 | * @return EINA_TRUE on successful creation, EINA_FALSE otherwise. |
156 | * | 194 | * |
157 | * The directory is created with the mode: S_IRUSR | S_IWUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH | 195 | * This function creates the directory @p dir with the mode S_IRUSR | |
196 | * S_IWUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH. On | ||
197 | * success, it returns EINA_TRUE, EINA_FALSE otherwise. | ||
158 | */ | 198 | */ |
159 | EAPI Eina_Bool | 199 | EAPI Eina_Bool |
160 | ecore_file_mkdir(const char *dir) | 200 | ecore_file_mkdir(const char *dir) |
@@ -164,12 +204,17 @@ ecore_file_mkdir(const char *dir) | |||
164 | } | 204 | } |
165 | 205 | ||
166 | /** | 206 | /** |
167 | * Create complete directory in a batch. | 207 | * @brief Create complete directory in a batch. |
168 | * | 208 | * |
169 | * @param dirs list of directories, null terminated. | 209 | * @param dirs The list of directories, null terminated. |
170 | * @return number of successful directories created, -1 if dirs is NULL. | 210 | * @return The number of successful directories created, -1 if dirs is |
211 | * @c NULL. | ||
171 | * | 212 | * |
172 | * @see ecore_file_mkdir() and ecore_file_mkpaths() | 213 | * This function creates all the directories that are in the null |
214 | * terminated array @p dirs. The function loops over the directories | ||
215 | * and call ecore_file_mkdir(). This function returns -1 if @p dirs is | ||
216 | * @c NULL, otherwise if returns the number of suceesfully created | ||
217 | * directories. | ||
173 | */ | 218 | */ |
174 | EAPI int | 219 | EAPI int |
175 | ecore_file_mkdirs(const char **dirs) | 220 | ecore_file_mkdirs(const char **dirs) |
@@ -185,19 +230,22 @@ ecore_file_mkdirs(const char **dirs) | |||
185 | } | 230 | } |
186 | 231 | ||
187 | /** | 232 | /** |
188 | * Create complete list of sub-directories in a batch (optimized). | 233 | * @brief Create complete list of sub-directories in a batch (optimized). |
189 | * | ||
190 | * @param base the base directory to act on, will be created if does | ||
191 | * not exists. | ||
192 | * @param subdirs list of directories, null terminated. These are | ||
193 | * created similarly to ecore_file_mkdir(), so same mode and whole | ||
194 | * path to that point must exists. So if creating base/a/b/c, | ||
195 | * provide subdirs with "a", "a/b" and "a/b/c" in that order! | ||
196 | * | 234 | * |
197 | * @return number of successful directories created, -1 if subdirs or | 235 | * @param base The base directory to act on. |
198 | * base is NULL or invalid. | 236 | * @param subdirs The list of directories, null terminated. |
237 | * @return number of successful directories created, -1 on failure. | ||
199 | * | 238 | * |
200 | * @see ecore_file_mkdir() and ecore_file_mkpaths() | 239 | * This function creates all the directories that are in the null |
240 | * terminated array @p dirs in the @p base directory. If @p base does | ||
241 | * not exist, it will be created. The function loops over the directories | ||
242 | * and call ecore_file_mkdir(). The whole path of the directories must | ||
243 | * exist. So if base/a/b/c wants to be created, @p subdirs must | ||
244 | * contain "a", "a/b" and "a/b/c", in that order. This function | ||
245 | * returns -1 if @p dirs or @p base are @c NULL, or if @p base is | ||
246 | * empty ("\0"). It returns 0 is @p base is not a directory or | ||
247 | * invalid, or if it can't be created. Otherwise if returns the number | ||
248 | * of suceesfully created directories. | ||
201 | */ | 249 | */ |
202 | EAPI int | 250 | EAPI int |
203 | ecore_file_mksubdirs(const char *base, const char **subdirs) | 251 | ecore_file_mksubdirs(const char *base, const char **subdirs) |
@@ -277,9 +325,13 @@ ecore_file_mksubdirs(const char *base, const char **subdirs) | |||
277 | } | 325 | } |
278 | 326 | ||
279 | /** | 327 | /** |
280 | * Delete the given dir | 328 | * @brief Delete the given directory. |
281 | * @param dir The name of the directory to delete | 329 | * |
282 | * @return EINA_TRUE on success, EINA_FALSE on failure | 330 | * @param dir The name of the directory to delete. |
331 | * @return EINA_TRUE on success, EINA_FALSE otherwise. | ||
332 | * | ||
333 | * This function deletes @p dir. It returns EINA_TRUE on success, | ||
334 | * EINA_FALSE otherwise. | ||
283 | */ | 335 | */ |
284 | EAPI Eina_Bool | 336 | EAPI Eina_Bool |
285 | ecore_file_rmdir(const char *dir) | 337 | ecore_file_rmdir(const char *dir) |
@@ -289,9 +341,13 @@ ecore_file_rmdir(const char *dir) | |||
289 | } | 341 | } |
290 | 342 | ||
291 | /** | 343 | /** |
292 | * Delete the given file | 344 | * @brief Delete the given file. |
293 | * @param file The name of the file to delete | 345 | * |
294 | * @return EINA_TRUE on success, EINA_FALSE on failure | 346 | * @param file The name of the file to delete. |
347 | * @return EINA_TRUE on success, EINA_FALSE otherwise. | ||
348 | * | ||
349 | * This function deletes @p file. It returns EINA_TRUE on success, | ||
350 | * EINA_FALSE otherwise. | ||
295 | */ | 351 | */ |
296 | EAPI Eina_Bool | 352 | EAPI Eina_Bool |
297 | ecore_file_unlink(const char *file) | 353 | ecore_file_unlink(const char *file) |
@@ -301,9 +357,13 @@ ecore_file_unlink(const char *file) | |||
301 | } | 357 | } |
302 | 358 | ||
303 | /** | 359 | /** |
304 | * Remove the given file or directory | 360 | * @brief Remove the given file or directory. |
305 | * @param file The name of the file or directory to delete | 361 | * |
306 | * @return EINA_TRUE on success, EINA_FALSE on failure | 362 | * @param file The name of the file or directory to delete. |
363 | * @return EINA_TRUE on success, EINA_FALSE otherwise. | ||
364 | * | ||
365 | * This function removes @p file. It returns EINA_TRUE on success, | ||
366 | * EINA_FALSE otherwise. | ||
307 | */ | 367 | */ |
308 | EAPI Eina_Bool | 368 | EAPI Eina_Bool |
309 | ecore_file_remove(const char *file) | 369 | ecore_file_remove(const char *file) |
@@ -313,11 +373,14 @@ ecore_file_remove(const char *file) | |||
313 | } | 373 | } |
314 | 374 | ||
315 | /** | 375 | /** |
316 | * Delete a directory and all its contents | 376 | * @brief Delete the given directory and all its contents. |
317 | * @param dir The name of the directory to delete | ||
318 | * @return EINA_TRUE on success, EINA_FALSE on failure | ||
319 | * | 377 | * |
320 | * If dir is a link only the link is removed | 378 | * @param dir The name of the directory to delete. |
379 | * @return EINA_TRUE on success, EINA_FALSE otherwise. | ||
380 | * | ||
381 | * This function delete @p dir and all its contents. If @p dir is a | ||
382 | * link only the link is removed. It returns EINA_TRUE on success, | ||
383 | * EINA_FALSE otherwise. | ||
321 | */ | 384 | */ |
322 | EAPI Eina_Bool | 385 | EAPI Eina_Bool |
323 | ecore_file_recursive_rm(const char *dir) | 386 | ecore_file_recursive_rm(const char *dir) |
@@ -377,11 +440,15 @@ _ecore_file_mkpath_if_not_exists(const char *path) | |||
377 | } | 440 | } |
378 | 441 | ||
379 | /** | 442 | /** |
380 | * Create a complete path | 443 | * @brief Create a complete path. |
444 | * | ||
381 | * @param path The path to create | 445 | * @param path The path to create |
382 | * @return EINA_TRUE on success, EINA_FALSE on failure | 446 | * @return EINA_TRUE on success, EINA_FALSE otherwise. |
383 | * | 447 | * |
384 | * @see ecore_file_mkpaths() and ecore_file_mkdir() | 448 | * This function create @p path and all the subdirectories it |
449 | * contains. The separator is '/' so, on Windows, '\' must be replaced | ||
450 | * by '/'. If @p path exists, this function returns EINA_TRUE | ||
451 | * immediatly. It returns EINA_TRUE on success, EINA_FALSE otherwise. | ||
385 | */ | 452 | */ |
386 | EAPI Eina_Bool | 453 | EAPI Eina_Bool |
387 | ecore_file_mkpath(const char *path) | 454 | ecore_file_mkpath(const char *path) |
@@ -407,12 +474,17 @@ ecore_file_mkpath(const char *path) | |||
407 | } | 474 | } |
408 | 475 | ||
409 | /** | 476 | /** |
410 | * Create complete paths in a batch. | 477 | * @brief Create complete paths in a batch. |
411 | * | 478 | * |
412 | * @param paths list of paths, null terminated. | 479 | * @param paths list of paths, null terminated. |
413 | * @return number of successful paths created, -1 if paths is NULL. | 480 | * @return number of successful paths created, -1 if paths is NULL. |
414 | * | 481 | * |
415 | * @see ecore_file_mkpath() and ecore_file_mkdirs() | 482 | * This function creates all the directories that are in the null |
483 | * terminated array @p paths. The function loops over the directories | ||
484 | * and call ecore_file_mkpath(), hence on Windows, '\' must be | ||
485 | * replaced by '/' before calling that function. This function | ||
486 | * returns -1 if @p paths is @c NULL. Otherwise if returns the number | ||
487 | * of suceesfully created directories. | ||
416 | */ | 488 | */ |
417 | EAPI int | 489 | EAPI int |
418 | ecore_file_mkpaths(const char **paths) | 490 | ecore_file_mkpaths(const char **paths) |
@@ -428,10 +500,16 @@ ecore_file_mkpaths(const char **paths) | |||
428 | } | 500 | } |
429 | 501 | ||
430 | /** | 502 | /** |
431 | * Copy a file | 503 | * @brief Copy the given file to the given destination. |
432 | * @param src The name of the source file | 504 | * |
433 | * @param dst The name of the destination file | 505 | * @param src The name of the source file. |
434 | * @return EINA_TRUE on success, EINA_FALSE on failure | 506 | * @param dst The name of the destination file. |
507 | * @return EINA_TRUE on success, EINA_FALSE otherwise. | ||
508 | * | ||
509 | * This function copies @p src to @p dst. If the absolute path name of | ||
510 | * @p src and @p dst can not be computed, or if they are equal, or if | ||
511 | * the copy fails, the function returns EINA_FALSE, otherwise it | ||
512 | * returns EINA_TRUE. | ||
435 | */ | 513 | */ |
436 | EAPI Eina_Bool | 514 | EAPI Eina_Bool |
437 | ecore_file_cp(const char *src, const char *dst) | 515 | ecore_file_cp(const char *src, const char *dst) |
@@ -463,10 +541,14 @@ ecore_file_cp(const char *src, const char *dst) | |||
463 | } | 541 | } |
464 | 542 | ||
465 | /** | 543 | /** |
466 | * Move a file | 544 | * @brief Move the given file to the given destination. |
467 | * @param src The name of the source file | 545 | * |
468 | * @param dst The name of the destination file | 546 | * @param src The name of the source file. |
469 | * @return EINA_TRUE on success, EINA_FALSE on failure | 547 | * @param dst The name of the destination file. |
548 | * @return EINA_TRUE on success, EINA_FALSE otherwise. | ||
549 | * | ||
550 | * This function moves @p src to @p dst. It returns EINA_TRUE on | ||
551 | * success, EINA_FALSE otherwise. | ||
470 | */ | 552 | */ |
471 | EAPI Eina_Bool | 553 | EAPI Eina_Bool |
472 | ecore_file_mv(const char *src, const char *dst) | 554 | ecore_file_mv(const char *src, const char *dst) |
@@ -537,10 +619,15 @@ FAIL: | |||
537 | } | 619 | } |
538 | 620 | ||
539 | /** | 621 | /** |
540 | * Create a symbolic link | 622 | * @brief Create a symbolic link. |
541 | * @param src The name of the file to link | 623 | * |
542 | * @param dest The name of link | 624 | * @param src The name of the file to link. |
543 | * @return EINA_TRUE on success, EINA_FALSE on failure | 625 | * @param dest The name of link. |
626 | * @return EINA_TRUE on success, EINA_FALSE otherwise. | ||
627 | * | ||
628 | * This function create the symbolic link @p dest of @p src. This | ||
629 | * function does not work on Windows. It returns EINA_TRUE on success, | ||
630 | * EINA_FALSE otherwise. | ||
544 | */ | 631 | */ |
545 | EAPI Eina_Bool | 632 | EAPI Eina_Bool |
546 | ecore_file_symlink(const char *src, const char *dest) | 633 | ecore_file_symlink(const char *src, const char *dest) |
@@ -551,10 +638,16 @@ ecore_file_symlink(const char *src, const char *dest) | |||
551 | } | 638 | } |
552 | 639 | ||
553 | /** | 640 | /** |
554 | * Get the canonicalized absolute pathname | 641 | * @brief Get the canonicalized absolute path name. |
555 | * @param file The file path | 642 | * |
556 | * @return The canonicalized absolute pathname; on failure it will return | 643 | * @param file The file path. |
557 | * an empty string | 644 | * @return The canonicalized absolute pathname or an empty string on |
645 | * failure. | ||
646 | * | ||
647 | * This function returns the absolute path name of @p file as a newly | ||
648 | * allocated string. If @p file is @c NULL, or on error, this function | ||
649 | * returns an empty string. Otherwise, it returns the absolute path | ||
650 | * name. When not needed anymore, the returned value must be freed. | ||
558 | */ | 651 | */ |
559 | EAPI char * | 652 | EAPI char * |
560 | ecore_file_realpath(const char *file) | 653 | ecore_file_realpath(const char *file) |
@@ -572,9 +665,13 @@ ecore_file_realpath(const char *file) | |||
572 | } | 665 | } |
573 | 666 | ||
574 | /** | 667 | /** |
575 | * Get the filename from a give path | 668 | * Get the filename from a given path. |
576 | * @param path The complete path | 669 | * |
577 | * @return Only the file name | 670 | * @param path The complete path. |
671 | * @return The file name. | ||
672 | * | ||
673 | * This function returns the file name of @p path. If @p path is | ||
674 | * @c NULL, the functions returns @c NULL. | ||
578 | */ | 675 | */ |
579 | EAPI const char * | 676 | EAPI const char * |
580 | ecore_file_file_get(const char *path) | 677 | ecore_file_file_get(const char *path) |
@@ -588,9 +685,15 @@ ecore_file_file_get(const char *path) | |||
588 | } | 685 | } |
589 | 686 | ||
590 | /** | 687 | /** |
591 | * Get the directory where file reside | 688 | * @brief Get the directory where the given file resides. |
592 | * @param file The name of the file | 689 | * |
593 | * @return The directory name | 690 | * @param file The name of the file. |
691 | * @return The directory name. | ||
692 | * | ||
693 | * This function returns the directory where @p file resides as anewly | ||
694 | * allocated string. If @p file is @c NULL or on error, this function | ||
695 | * returns @c NULL. When not needed anymore, the returned value must | ||
696 | * be freed. | ||
594 | */ | 697 | */ |
595 | EAPI char * | 698 | EAPI char * |
596 | ecore_file_dir_get(const char *file) | 699 | ecore_file_dir_get(const char *file) |
@@ -606,9 +709,13 @@ ecore_file_dir_get(const char *file) | |||
606 | } | 709 | } |
607 | 710 | ||
608 | /** | 711 | /** |
609 | * Check if file can be read | 712 | * @brief Check if the given file can be read. |
610 | * @param file The name of the file | 713 | * |
611 | * @return EINA_TRUE if the file is readable, EINA_FALSE otherwise | 714 | * @param file The name of the file. |
715 | * @return EINA_TRUE if the file is readable, EINA_FALSE otherwise. | ||
716 | * | ||
717 | * This function returns EINA_TRUE if @p file can be read, EINA_FALSE | ||
718 | * otherwise. | ||
612 | */ | 719 | */ |
613 | EAPI Eina_Bool | 720 | EAPI Eina_Bool |
614 | ecore_file_can_read(const char *file) | 721 | ecore_file_can_read(const char *file) |
@@ -619,9 +726,13 @@ ecore_file_can_read(const char *file) | |||
619 | } | 726 | } |
620 | 727 | ||
621 | /** | 728 | /** |
622 | * Check if file can be written | 729 | * @brief Check if the given file can be written. |
623 | * @param file The name of the file | 730 | * |
624 | * @return EINA_TRUE if the file is writable, EINA_FALSE otherwise | 731 | * @param file The name of the file. |
732 | * @return EINA_TRUE if the file is writable, EINA_FALSE otherwise. | ||
733 | * | ||
734 | * This function returns EINA_TRUE if @p file can be written, EINA_FALSE | ||
735 | * otherwise. | ||
625 | */ | 736 | */ |
626 | EAPI Eina_Bool | 737 | EAPI Eina_Bool |
627 | ecore_file_can_write(const char *file) | 738 | ecore_file_can_write(const char *file) |
@@ -632,9 +743,13 @@ ecore_file_can_write(const char *file) | |||
632 | } | 743 | } |
633 | 744 | ||
634 | /** | 745 | /** |
635 | * Check if file can be executed | 746 | * @bbrief Check if the given file can be executed. |
636 | * @param file The name of the file | 747 | * |
637 | * @return EINA_TRUE if the file can be executed, EINA_FALSE otherwise | 748 | * @param file The name of the file. |
749 | * @return EINA_TRUE if the file can be executed, EINA_FALSE otherwise. | ||
750 | * | ||
751 | * This function returns EINA_TRUE if @p file can be executed, EINA_FALSE | ||
752 | * otherwise. | ||
638 | */ | 753 | */ |
639 | EAPI Eina_Bool | 754 | EAPI Eina_Bool |
640 | ecore_file_can_exec(const char *file) | 755 | ecore_file_can_exec(const char *file) |
@@ -645,9 +760,15 @@ ecore_file_can_exec(const char *file) | |||
645 | } | 760 | } |
646 | 761 | ||
647 | /** | 762 | /** |
648 | * Get the path pointed by link | 763 | * @brief Get the path pointed by the given link. |
649 | * @param link The name of the link | 764 | * |
650 | * @return The path pointed by link or NULL | 765 | * @param link The name of the link. |
766 | * @return The path pointed by link or NULL. | ||
767 | * | ||
768 | * This function returns the path pointed by @p link as a newly | ||
769 | * allocated string. This function does not work on Windows. On | ||
770 | * failure, the function returns @c NULL. When not needed anymore, the | ||
771 | * returned value must be freed. | ||
651 | */ | 772 | */ |
652 | EAPI char * | 773 | EAPI char * |
653 | ecore_file_readlink(const char *link) | 774 | ecore_file_readlink(const char *link) |
@@ -661,14 +782,21 @@ ecore_file_readlink(const char *link) | |||
661 | } | 782 | } |
662 | 783 | ||
663 | /** | 784 | /** |
664 | * Get the list of the files and directories in a given directory. The list | 785 | * @brief Get the list of the files and directories in the given |
665 | * will be sorted with strcoll as compare function. That means that you may | 786 | * directory. |
666 | * want to set the current locale for the category LC_COLLATE with setlocale(). | 787 | * |
667 | * For more information see the manual pages of strcoll and setlocale. | ||
668 | * The list will not contain the directory entries for '.' and '..'. | ||
669 | * @param dir The name of the directory to list | 788 | * @param dir The name of the directory to list |
670 | * @return Return an Eina_List containing all the files in the directory; | 789 | * @return Return an Eina_List containing all the files in the directory; |
671 | * on failure it returns NULL. | 790 | * on failure it returns NULL. |
791 | * | ||
792 | * This function returns a list of allocated strings of all the files | ||
793 | * and directories contained in @p dir. The list will be sorted with | ||
794 | * strcoll as compare function. That means that you may want to set | ||
795 | * the current locale for the category LC_COLLATE with | ||
796 | * setlocale(). For more information see the manual pages of strcoll | ||
797 | * and setlocale. The list will not contain the directory entries for | ||
798 | * '.' and '..'. On failure, @c NULL is returned. When not needed | ||
799 | * anymore, the list elements must be freed. | ||
672 | */ | 800 | */ |
673 | EAPI Eina_List * | 801 | EAPI Eina_List * |
674 | ecore_file_ls(const char *dir) | 802 | ecore_file_ls(const char *dir) |
@@ -697,7 +825,14 @@ ecore_file_ls(const char *dir) | |||
697 | } | 825 | } |
698 | 826 | ||
699 | /** | 827 | /** |
700 | * FIXME: To be documented. | 828 | * @brief Return the executable from the given command. |
829 | * | ||
830 | * @param app The application command, with parameters. | ||
831 | * | ||
832 | * This function returns the executable from @p app as a newly | ||
833 | * allocated string. Arguments are removed and escae characters are | ||
834 | * handled. If @p app is @c NULL, or on failure, the function returns | ||
835 | * @c NULL. When not needed anymore, the returned value must be freed. | ||
701 | */ | 836 | */ |
702 | EAPI char * | 837 | EAPI char * |
703 | ecore_file_app_exe_get(const char *app) | 838 | ecore_file_app_exe_get(const char *app) |
@@ -792,7 +927,7 @@ restart: | |||
792 | in_quot_dbl = 0; | 927 | in_quot_dbl = 0; |
793 | else | 928 | else |
794 | { | 929 | { |
795 | /* techcincally this is wrong. double quotes also accept | 930 | /* technically this is wrong. double quotes also accept |
796 | * special chars: | 931 | * special chars: |
797 | * | 932 | * |
798 | * $, `, \ | 933 | * $, `, \ |
@@ -845,10 +980,16 @@ restart: | |||
845 | } | 980 | } |
846 | 981 | ||
847 | /** | 982 | /** |
848 | * Add the escape sequence ('\\') to the given filename | 983 | * @brief Add the escape sequence ('\\') to the given file name. |
849 | * @param filename The file name | 984 | * |
850 | * @return The file name with special characters escaped; if the length of the | 985 | * @param filename The file name. |
851 | * resulting string is longer than PATH_MAX it will return NULL | 986 | * @return The file name with special characters escaped. |
987 | * | ||
988 | * This function adds the escape sequence ('\\') to the given file | ||
989 | * name and returns the result as a newly allocated string. If the | ||
990 | * length of the returned string is longer than PATH_MAX, or on | ||
991 | * failure, @c NULL is returned. When not needed anymore, the returned | ||
992 | * value must be freed. | ||
852 | */ | 993 | */ |
853 | EAPI char * | 994 | EAPI char * |
854 | ecore_file_escape_name(const char *filename) | 995 | ecore_file_escape_name(const char *filename) |
@@ -885,15 +1026,25 @@ ecore_file_escape_name(const char *filename) | |||
885 | } | 1026 | } |
886 | 1027 | ||
887 | /** | 1028 | /** |
888 | * Remove the extension from a given path | 1029 | * @bried Remove the extension from the given file name. |
889 | * @param path The name of the file | 1030 | * |
890 | * @return A newly allocated string with the extension stripped out or NULL on errors | 1031 | * @param path The name of the file. |
1032 | * @return A newly allocated string with the extension stripped out or | ||
1033 | * NULL on errors. | ||
1034 | * | ||
1035 | * This function removes the extension from @p path and returns the | ||
1036 | * result as a newly allocated string. If @p path is @c NULL, or on | ||
1037 | * failure, the function returns @c NULL. When not needed anymore, the | ||
1038 | * returned value must be freed. | ||
891 | */ | 1039 | */ |
892 | EAPI char * | 1040 | EAPI char * |
893 | ecore_file_strip_ext(const char *path) | 1041 | ecore_file_strip_ext(const char *path) |
894 | { | 1042 | { |
895 | char *p, *file = NULL; | 1043 | char *p, *file = NULL; |
896 | 1044 | ||
1045 | if (!path) | ||
1046 | return NULL; | ||
1047 | |||
897 | p = strrchr(path, '.'); | 1048 | p = strrchr(path, '.'); |
898 | if (!p) | 1049 | if (!p) |
899 | file = strdup(path); | 1050 | file = strdup(path); |
@@ -911,9 +1062,15 @@ ecore_file_strip_ext(const char *path) | |||
911 | } | 1062 | } |
912 | 1063 | ||
913 | /** | 1064 | /** |
914 | * Check if the given directory is empty. The '.' and '..' files will be ignored. | 1065 | * @brief Check if the given directory is empty. |
915 | * @param dir The name of the directory to check | 1066 | * |
916 | * @return 1 if directory is empty, 0 if it has at least one file or -1 in case of errors | 1067 | * @param dir The name of the directory to check. |
1068 | * @return 1 if directory is empty, 0 if it has at least one file or | ||
1069 | * -1 in case of errors. | ||
1070 | * | ||
1071 | * This functions checks if @p dir is empty. The '.' and '..' files | ||
1072 | * will be ignored. If @p dir is empty, 1 is returned, if it contains | ||
1073 | * at least 1 file, 0 is returned. On failure, -1 is returned. | ||
917 | */ | 1074 | */ |
918 | EAPI int | 1075 | EAPI int |
919 | ecore_file_dir_is_empty(const char *dir) | 1076 | ecore_file_dir_is_empty(const char *dir) |
@@ -936,3 +1093,7 @@ ecore_file_dir_is_empty(const char *dir) | |||
936 | closedir(dirp); | 1093 | closedir(dirp); |
937 | return 1; | 1094 | return 1; |
938 | } | 1095 | } |
1096 | |||
1097 | /** | ||
1098 | * @} | ||
1099 | */ | ||