src/include/eina_file.h

   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_Lines
 103  * A typedef to #_Eina_File_Lines.
 104  */
 105 typedef struct _Eina_File_Line Eina_File_Line;
 106
 107 /**
 108  * @typedef Eina_File_Dir_List_Cb
 109  * Type for a callback to be called when iterating over the files of a
 110  * directory.
 111  * @param The file name EXCLUDING the path
 112  * @param path The path passed to eina_file_dir_list()
 113  * @param data The data passed to eina_file_dir_list()
 114  */
 115 typedef void (*Eina_File_Dir_List_Cb)(const char *name, const char *path, void *data);
 116
 117 /**
 118  * @typedef Eina_File_Type
 119  * file type in Eina_File_Direct_Info.
 120  */
 121 typedef enum {
 122   EINA_FILE_UNKNOWN, /**< Unknown file type. */
 123   EINA_FILE_FIFO,    /**< Named pipe (FIFO) type (unused on Windows). */
 124   EINA_FILE_CHR,     /**< Character device type (unused on Windows). */
 125   EINA_FILE_DIR,     /**< Directory type. */
 126   EINA_FILE_BLK,     /**< Block device type (unused on Windows). */
 127   EINA_FILE_REG,     /**< Regular file type. */
 128   EINA_FILE_LNK,     /**< Symbolic link type. */
 129   EINA_FILE_SOCK,    /**< UNIX domain socket type (unused on Windows). */
 130   EINA_FILE_WHT      /**< Whiteout file type (unused on Windows). */
 131 } Eina_File_Type;
 132
 133 typedef struct _Eina_File Eina_File;
 134 /**
 135  * @typedef Eina_File_Populate
 136  * File access type used in Eina_File_Direct_info.
 137  */
 138 typedef enum {
 139   EINA_FILE_RANDOM,     /**< Advise random memory access to the mapped memory. */
 140   EINA_FILE_SEQUENTIAL, /**< Advise sequential memory access to the mapped memory. */
 141   EINA_FILE_WILLNEED,   /**< Advise need for all the mapped memory. */
 142   EINA_FILE_POPULATE    /**< Request all the mapped memory. */
 143 } Eina_File_Populate;
 144
 145 /* Why do this? Well PATH_MAX may vary from when eina itself is compiled
 146  * to when the app using eina is compiled. exposing the path buffer below
 147  * can't safely and portably vary based on how/when you compile. it should
 148  * always be the same for both eina inside AND for apps outside that use eina
 149  * so define this to 8192 - most PATH_MAX values are like 4096 or 1024 (with
 150  * windows i think being 260), so 8192 should cover almost all cases. there
 151  * is a possibility that PATH_MAX could be more than 8192. if anyone spots
 152  * a path_max that is bigger - let us know, but, for now we will assume
 153  * it never happens */
 154 /**
 155  * @def EINA_PATH_MAX
 156  * @brief The constant defined as the highest value for PATH_MAX.
 157  */
 158 #define EINA_PATH_MAX 8192
 159 /**
 160  * @struct _Eina_File_Direct_Info
 161  * A structure to store informations of a path.
 162  */
 163 struct _Eina_File_Direct_Info
 164 {
 165    size_t               path_length; /**< size of the whole path */
 166    size_t               name_length; /**< size of the filename/basename component */
 167    size_t               name_start; /**< where the filename/basename component starts */
 168    Eina_File_Type       type; /**< file type */
 169    char                 path[EINA_PATH_MAX]; /**< the path */
 170 };
 171
 172 /**
 173  * @struct _Eina_Stat
 174  * A structure to store informations of a path.
 175  * @since 1.2
 176  */
 177 struct _Eina_Stat
 178 {
 179    unsigned long int    dev;
 180    unsigned long int    ino;
 181    unsigned int         mode;
 182    unsigned int         nlink;
 183    unsigned int         uid;
 184    unsigned int         gid;
 185    unsigned long int    rdev;
 186    unsigned long int    size;
 187    unsigned long int    blksize;
 188    unsigned long int    blocks;
 189    unsigned long int    atime;
 190    unsigned long int    atimensec;
 191    unsigned long int    mtime;
 192    unsigned long int    mtimensec;
 193    unsigned long int    ctime;
 194    unsigned long int    ctimensec;
 195 };
 196
 197 /**
 198  * @struct _Eina_File_Line
 199  * A structure to store information of line
 200  * @since 1.3
 201  */
 202 struct _Eina_File_Line
 203 {
 204   const char *start;
 205   const char *end;
 206   unsigned int index;
 207   unsigned long long length;
 208 };
 209
 210 /**
 211  * @def EINA_FILE_DIR_LIST_CB
 212  * @brief cast to an #Eina_File_Dir_List_Cb.
 213  *
 214  * @param function The function to cast.
 215  *
 216  * This macro casts @p function to Eina_File_Dir_List_Cb.
 217  */
 218 #define EINA_FILE_DIR_LIST_CB(function) ((Eina_File_Dir_List_Cb)function)
 219
 220
 221 /**
 222  * @brief List all files on the directory calling the function for every file found.
 223  *
 224  * @param dir The directory name.
 225  * @param recursive Iterate recursively in the directory.
 226  * @param cb The callback to be called.
 227  * @param data The data to pass to the callback.
 228  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 229  *
 230  * This function calls @p cb for each file that is in @p dir. To have @p cb
 231  * called on files that are in subdirectories of @p dir @p recursive should
 232  * be #EINA_TRUE. In other words if @p recursive is #EINA_FALSE, only direct children
 233  * of @p dir will be operated on, if @p recursive is #EINA_TRUE the entire tree
 234  * of files that is below @p dir will be operated on.
 235  *
 236  * If @p cb or @p dir are @c NULL, or if @p dir is a string of size 0,
 237  * or if @p dir can not be opened, this function returns #EINA_FALSE
 238  * immediately. otherwise, it returns #EINA_TRUE.
 239  */
 240 EAPI Eina_Bool eina_file_dir_list(const char           *dir,
 241                                   Eina_Bool             recursive,
 242                                   Eina_File_Dir_List_Cb cb,
 243                                   void                 *data) EINA_ARG_NONNULL(1, 3);
 244
 245 /**
 246  * @brief Split a path according to the delimiter of the filesystem.
 247  *
 248  * @param path The path to split.
 249  * @return An array of the parts of the path to split.
 250  *
 251  * This function splits @p path according to the delimiter of the used
 252  * filesystem. If  @p path is @c NULL or if the array can not be
 253  * created, @c NULL is returned, otherwise, an array with each part of @p path
 254  * is returned.
 255  */
 256 EAPI Eina_Array    *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
 257
 258 /**
 259  * @brief Get an iterator to list the content of a directory.
 260  *
 261  * @param  dir The name of the directory to list
 262  * @return Return an Eina_Iterator that will walk over the files and directories
 263  *         in @p dir. On failure it will return @c NULL.
 264  *
 265  * Returns an iterator for shared strings, the name of each file in @p dir will
 266  * only be fetched when advancing the iterator, which means there is very little
 267  * cost associated with creating the list and stopping halfway through it.
 268  *
 269  * @warning The iterator will hand the user a stringshared value with the full
 270  * path. The user must free the string using eina_stringshare_del() on it.
 271  *
 272  * @note The container for the iterator is of type DIR*.
 273  * @note The iterator will walk over '.' and '..' without returning them.
 274  *
 275  * @see eina_file_direct_ls()
 276  */
 277 EAPI Eina_Iterator *eina_file_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
 278
 279 /**
 280  * @brief Get an iterator to list the content of a directory, with direct
 281  * information.
 282  *
 283  * @param  dir The name of the directory to list
 284  *
 285  * @return Return an Eina_Iterator that will walk over the files and
 286  *         directory in the pointed directory. On failure it will
 287  *         return NULL.
 288  *
 289  * Returns an iterator for Eina_File_Direct_Info, the name of each file in @p
 290  * dir will only be fetched when advancing the iterator, which means there is
 291  * cost associated with creating the list and stopping halfway through it.
 292  *
 293  * @warning The Eina_File_Direct_Info returned by the iterator <b>must not</b>
 294  * be modified in any way.
 295  * @warning When the iterator is advanced or deleted the Eina_File_Direct_Info
 296  * returned is no longer valid.
 297  *
 298  * @note The container for the iterator is of type DIR*.
 299  * @note The iterator will walk over '.' and '..' without returning them.
 300  * @note The difference between this function and eina_file_direct_ls() is that
 301  *       it guarantees the file type information will be correct incurring a
 302  *       possible performance penalty.
 303  *
 304  * @see eina_file_direct_ls()
 305  */
 306 EAPI Eina_Iterator *eina_file_stat_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
 307
 308 /**
 309  * @brief Use information provided by Eina_Iterator of eina_file_stat_ls or eina_file_direct_ls
 310  * to call stat in the most efficient way on your system.
 311  *
 312  * @param container The container returned by the Eina_Iterator using eina_iterator_container_get().
 313  * @param info The content of the current Eina_File_Direct_Info provided by the Eina_Iterator
 314  * @param buf Where to put the result of the stat
 315  * @return On success @c 0 is returned, On error @c -1 is returned and errno is set appropriately.
 316  *
 317  * This function calls fstatat or stat depending on what your system supports. This makes it efficient and simple
 318  * to use on your side without complex detection already done inside Eina on what the system can do.
 319  *
 320  * @see eina_file_direct_ls()
 321  * @see eina_file_stat_ls()
 322  * @since 1.2
 323  */
 324 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);
 325
 326 /**
 327  * @brief Get an iterator to list the content of a directory, with direct
 328  * information.
 329  *
 330  * @param  dir The name of the directory to list
 331  *
 332  * @return Return an Eina_Iterator that will walk over the files and
 333  *         directory in the pointed directory. On failure it will
 334  *         return @c NULL.
 335  *
 336  * Returns an iterator for Eina_File_Direct_Info, the name of each file in @p
 337  * dir will only be fetched when advancing the iterator, which means there is
 338  * cost associated with creating the list and stopping halfway through it.
 339  *
 340  * @warning If readdir_r doesn't contain file type information file type will
 341  * be DT_UNKNOW.
 342  * @warning The Eina_File_Direct_Info returned by the iterator <b>must not</b>
 343  * be modified in any way.
 344  * @warning When the iterator is advanced or deleted the Eina_File_Direct_Info
 345  * returned is no longer valid.
 346  *
 347  * @note The container for the iterator is of type DIR*.
 348  * @note The iterator will walk over '.' and '..' without returning them.
 349  * @note The difference between this function and eina_file_stat_ls() is that
 350  *       it may not get the file type information however it is likely to be
 351  *       faster.
 352  *
 353  * @see eina_file_ls()
 354  */
 355 EAPI Eina_Iterator *eina_file_direct_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
 356
 357 /**
 358  * @brief Sanitize file path.
 359  *
 360  * @param path The path to sanitize
 361  *
 362  * @return an allocated string with the sanitized path.
 363  *
 364  * This function take care of adding the current working directory if it's a
 365  * relative path and also remove all '..' and '//' reference in the original
 366  * path.
 367  *
 368  * @since 1.1
 369  */
 370 EAPI char *eina_file_path_sanitize(const char *path);
 371
 372 /**
 373  * @brief Get a read-only handler to a file.
 374  *
 375  * @param name Filename to open
 376  * @param shared Requested a shm
 377  * @return Eina_File handle to the file
 378  *
 379  * Opens a file in read-only mode. @p name should be an absolute path. An
 380  * Eina_File handle can be shared among multiple instances if @p shared
 381  * is #EINA_TRUE.
 382  *
 383  * @since 1.1
 384  */
 385 EAPI Eina_File *eina_file_open(const char *name, Eina_Bool shared) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
 386
 387 /**
 388  * @brief Unref file handler.
 389  *
 390  * @param file File handler to unref.
 391  *
 392  * Decrement file's refcount and if it reaches zero close it.
 393  *
 394  * @since 1.1
 395  */
 396 EAPI void eina_file_close(Eina_File *file);
 397
 398 /**
 399  * @brief Get file size at open time.
 400  *
 401  * @param file The file handler to request the size from.
 402  * @return The length of the file.
 403  *
 404  * @since 1.1
 405  */
 406 EAPI size_t eina_file_size_get(Eina_File *file);
 407
 408 /**
 409  * @brief Get the last modification time of an open file.
 410  *
 411  * @param file The file handler to request the modification time from.
 412  * @return The last modification time.
 413  *
 414  * @since 1.1
 415  */
 416 EAPI time_t eina_file_mtime_get(Eina_File *file);
 417
 418 /**
 419  * @brief Get the filename of an open file.
 420  *
 421  * @param file The file handler to request the name from.
 422  * @return Stringshared filename of the file.
 423  *
 424  * @since 1.1
 425  */
 426 EAPI const char *eina_file_filename_get(Eina_File *file);
 427
 428 /**
 429  * @brief Get the eXtended attribute of an open file.
 430  *
 431  * @param file The file handler to request the eXtended attribute from.
 432  * @return an iterator.
 433  *
 434  * The iterator will list all eXtended attribute name without allocating
 435  * them, so you need to copy them yourself if needed.
 436  *
 437  * @since 1.2
 438  */
 439 EAPI Eina_Iterator *eina_file_xattr_get(Eina_File *file);
 440
 441 /**
 442  * @brief Get the eXtended attribute of an open file.
 443  *
 444  * @param file The file handler to request the eXtended attribute from.
 445  * @return an iterator.
 446  *
 447  * The iterator will list all eXtended attribute without allocating
 448  * them, so you need to copy them yourself if needed. It is returning
 449  * Eina_Xattr structure.
 450  *
 451  * @since 1.2
 452  */
 453 EAPI Eina_Iterator *eina_file_xattr_value_get(Eina_File *file);
 454
 455 /**
 456  * @brief Map all the file to a buffer.
 457  *
 458  * @param file The file handler to map in memory
 459  * @param rule The rule to apply to the mapped memory
 460  * @return A pointer to a buffer that map all the file content. @c NULL if it fail.
 461  *
 462  * @since 1.1
 463  */
 464 EAPI void *eina_file_map_all(Eina_File *file, Eina_File_Populate rule);
 465
 466 /**
 467  * @brief Map a part of the file.
 468  *
 469  * @param file The file handler to map in memory
 470  * @param rule The rule to apply to the mapped memory
 471  * @param offset The offset inside the file
 472  * @param length The length of the memory to map
 473  * @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.
 474  *
 475  * This does handle refcounting so it will share map that target the same memory area.
 476  *
 477  * @since 1.1
 478  */
 479 EAPI void *eina_file_map_new(Eina_File *file, Eina_File_Populate rule,
 480                              unsigned long int offset, unsigned long int length);
 481
 482 /**
 483  * @brief Unref and unmap memory if possible.
 484  *
 485  * @param file The file handler to unmap memory from.
 486  * @param map Memory map to unref and unmap.
 487  *
 488  * @since 1.1
 489  */
 490 EAPI void eina_file_map_free(Eina_File *file, void *map);
 491
 492 /**
 493  * @brief Map line by line in memory efficiently with an Eina_Iterator
 494  * @param file The file to run over
 495  * @return an Eina_Iterator that will produce @typedef Eina_File_Lines.
 496  *
 497  * This function return an iterator that will act like fgets without the
 498  * useless memcpy. Be aware that once eina_iterator_next has been called,
 499  * nothing garanty you that the memory will still be mapped.
 500  *
 501  * @since 1.3
 502  */
 503 EAPI Eina_Iterator *eina_file_map_lines(Eina_File *file);
 504
 505 /**
 506  * @brief Tell if their was an IO error during the life of a mmaped file
 507  *
 508  * @param file The file handler to the mmaped file.
 509  * @param map Memory map to check if an error occurred on it.
 510  * @return #EINA_TRUE if there was an IO error, #EINA_FALSE otherwise.
 511  *
 512  * @since 1.2
 513  */
 514 EAPI Eina_Bool eina_file_map_faulted(Eina_File *file, void *map);
 515
 516 /**
 517  * @}
 518  */
 519
 520 /**
 521  * @}
 522  */
 523
 524 #endif /* EINA_FILE_H_ */