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 #include "eina_tmpstr.h" 31 #include "eina_str.h" 32 33 /** 34 * @page eina_file_example_01_page 35 * @dontinclude eina_file_01.c 36 * 37 * For brevity, variable declarations and initialization are omitted 38 * from this page, however the full source code can be seen @ref 39 * eina_file_example_01 "here". 40 * 41 * Here we have a simple callback to print the name of a file and the path that 42 * contains it: 43 * @skip static 44 * @until } 45 * 46 * We can use this callback in the following call: 47 * @skipline eina_file_dir_list 48 * 49 * The above is a way to print the files in a directory, but it is not the only 50 * one: 51 * @until iterator_free 52 * 53 * And now two ways to get more information than just file names: 54 * @until iterator_free 55 * @until iterator_free 56 * 57 * The above mentioned ways of getting files on a list may produce the same output, but 58 * they have an important difference, eina_file_direct_ls() does @b not call 59 * stat, this means that on some systems it might not have file type 60 * information. On the other hand, it might be faster than eina_file_stat_ls(). 61 * 62 * @page eina_file_example_01 63 * @include eina_file_01.c 64 * @example eina_file_01.c 65 */ 66 67 /** 68 * @defgroup Eina_File_Group File 69 * @ingroup Eina_Tools_Group 70 * 71 * @brief This group discusses the functions to handle files and directories. 72 * 73 * @details These functions make it easier to do a number of file and directory operations 74 * such as getting the list of files in a directory, splitting paths, and finding 75 * out file size and type. 76 * 77 * @warning All functions in this group are @b blocking, which means they may 78 * take a long time to return; use them carefully. 79 * 80 * See an example @ref eina_file_example_01_page "here". 81 * 82 * @{ 83 */ 84 85 /** 86 * @typedef Eina_File_Direct_Info 87 * @brief A type for #_Eina_File_Direct_Info. 88 */ 89 typedef struct _Eina_File_Direct_Info Eina_File_Direct_Info; 90 91 /** 92 * @typedef Eina_Stat 93 * @brief A type for #_Eina_Stat. 94 * @since 1.2 95 */ 96 typedef struct _Eina_Stat Eina_Stat; 97 98 /** 99 * @typedef Eina_File_Line 100 * @brief A type for #_Eina_File_Line. 101 */ 102 typedef struct _Eina_File_Line Eina_File_Line; 103 104 /** 105 * @typedef Eina_File_Dir_List_Cb 106 * @brief Type for a callback to be called when iterating over the files of a 107 * directory. 108 * @param[in] name The file name EXCLUDING the path 109 * @param[in] path The path passed to eina_file_dir_list() 110 * @param[in] data The data passed to eina_file_dir_list() 111 */ 112 typedef void (*Eina_File_Dir_List_Cb)(const char *name, const char *path, void *data); 113 114 /** 115 * @typedef Eina_File_Type 116 * @brief Type for enumeration of a file type. 117 * @details This type is used in #Eina_File_Direct_Info. 118 */ 119 typedef enum { 120 EINA_FILE_UNKNOWN, /**< Unknown file type */ 121 EINA_FILE_FIFO, /**< Named pipe (FIFO) type (unused on Windows) */ 122 EINA_FILE_CHR, /**< Character device type (unused on Windows) */ 123 EINA_FILE_DIR, /**< Directory type */ 124 EINA_FILE_BLK, /**< Block device type (unused on Windows) */ 125 EINA_FILE_REG, /**< Regular file type */ 126 EINA_FILE_LNK, /**< Symbolic link type (unused on Windows) */ 127 EINA_FILE_SOCK, /**< UNIX domain socket type (unused on Windows) */ 128 EINA_FILE_WHT /**< Whiteout file type (unused on Windows) */ 129 } Eina_File_Type; 130 131 /** 132 * @typedef Eina_File 133 * @brief A file handle. 134 */ 135 typedef struct _Eina_File Eina_File; 136 137 /** 138 * @typedef Eina_File_Populate 139 * @brief Type for enumeration of a file access type. 140 * @details This type is used in #Eina_File_Direct_Info. 141 */ 142 typedef enum { 143 EINA_FILE_RANDOM, /**< Advise random memory access to the mapped memory */ 144 EINA_FILE_SEQUENTIAL, /**< Advise sequential memory access to the mapped memory */ 145 EINA_FILE_WILLNEED, /**< Advise need for all the mapped memory */ 146 EINA_FILE_POPULATE, /**< Request for all the mapped memory */ 147 EINA_FILE_DONTNEED, /**< Indicate that the memory is no longer needed. This may result in the memory being removed from any caches if applicable. @since 1.8 */ 148 EINA_FILE_REMOVE /**< This memory is to be released and any content will be lost. Subsequent accesses will succeed but return fresh memory as if accessed for the first time. This may not succeed if the filesystem does not support it. @since 1.8 */ 149 } Eina_File_Populate; 150 151 /* Why do this? Well PATH_MAX may vary from when eina itself is compiled 152 * to when the app using eina is compiled. Exposing the path buffer below 153 * can't safely and portably vary based on how/when you compile. It should 154 * always be the same for both eina inside AND for apps outside that use eina, 155 * so define this to 8192 - most PATH_MAX values are like 4096 or 1024 (with 156 * Windows I think being 260), so 8192 should cover almost all the cases. There 157 * is a possibility that PATH_MAX could be more than 8192. If anyone spots 158 * a path_max that is bigger - let us know, but, for now we assume that 159 * it never happens */ 160 /** 161 * @def EINA_PATH_MAX 162 * @brief Definition for the constant defined as the highest value for PATH_MAX. 163 */ 164 #define EINA_PATH_MAX 8192 165 166 /** 167 * @def EINA_PATH_SEP_C 168 * @brief The constant defined the path separator as the character '\' 169 * on Windows and '/' otherwise. 170 * 171 * @since 1.16 172 */ 173 /** 174 * @def EINA_PATH_SEP_S 175 * @brief The constant defined the path separator as the string "\" on Windows 176 * and "/" otherwise. 177 * 178 * @since 1.16 179 */ 180 #ifdef _WIN32 181 # define EINA_PATH_SEP_C '\\' 182 # define EINA_PATH_SEP_S "\\" 183 #else 184 # define EINA_PATH_SEP_C '/' 185 # define EINA_PATH_SEP_S "/" 186 #endif 187 188 /** 189 * @struct _Eina_File_Direct_Info 190 * @brief The structure to store information of a path. 191 */ 192 struct _Eina_File_Direct_Info 193 { 194 size_t path_length; /**< Size of the whole path */ 195 size_t name_length; /**< Size of the filename/basename component */ 196 size_t name_start; /**< Start position of the filename/basename component */ 197 Eina_File_Type type; /**< File type */ 198 char path[EINA_PATH_MAX]; /**< The path */ 199 }; 200 201 /** 202 * @struct _Eina_Stat 203 * @brief The structure to store some file statistics. 204 * @since 1.2 205 */ 206 struct _Eina_Stat 207 { 208 unsigned long int dev; /**< The device where this file is located */ 209 unsigned long int ino; /**< The inode */ 210 unsigned int mode; /**< The mode */ 211 unsigned int nlink; /**< The link number */ 212 unsigned int uid; /**< The owner user id */ 213 unsigned int gid; /**< The owner group id */ 214 unsigned long int rdev; /**< The remote device */ 215 unsigned long int size; /**< The file size in bytes */ 216 unsigned long int blksize; /**< The block size in bytes */ 217 unsigned long int blocks; /**< The number of blocks allocated */ 218 unsigned long int atime; /**< The timestamp when the file was last accessed */ 219 unsigned long int atimensec; /**< The nano version of the timestamp when the file was last accessed */ 220 unsigned long int mtime; /**< The timestamp when the file was last modified */ 221 unsigned long int mtimensec; /**< The nano version of the timestamp when the file was modified */ 222 unsigned long int ctime; /**< The timestamp when the file was created */ 223 unsigned long int ctimensec; /**< The nano version of the timestamp when the file was created */ 224 }; 225 226 /** 227 * @struct _Eina_File_Line 228 * @brief The structure to store information of a line. 229 * @since 1.3 230 */ 231 struct _Eina_File_Line 232 { 233 const char *start; /**< The start of the line */ 234 const char *end; /**< The end of the line */ 235 unsigned int index; /**< The line number */ 236 unsigned long long length; /**< The number of characters in the line */ 237 }; 238 239 /** 240 * @def EINA_FILE_DIR_LIST_CB 241 * @brief The macro to cast to an #Eina_File_Dir_List_Cb. 242 * @details This macro casts @p function to #Eina_File_Dir_List_Cb. 243 * @param[in] function The function to cast 244 * 245 */ 246 #define EINA_FILE_DIR_LIST_CB(function) ((Eina_File_Dir_List_Cb)function) 247 248 249 /** 250 * @brief Lists all the files on the directory by calling the function for every file found. 251 * @details This function calls @p cb for each file that is in @p dir. To have @p cb 252 * called on the files that are in subdirectories of @p dir, @p recursive should 253 * be #EINA_TRUE. In other words, if @p recursive is #EINA_FALSE, only direct children 254 * of @p dir are operated on, if @p recursive is #EINA_TRUE the entire tree 255 * of files that is below @p dir is operated on. 256 * 257 * If @p cb or @p dir is @c NULL or if @p dir is a string of size 0, 258 * or if @p dir cannot be opened, this function returns #EINA_FALSE 259 * immediately. Otherwise, it returns #EINA_TRUE. 260 * 261 * @param[in] dir The directory name 262 * @param[in] recursive Iterate recursively in the directory 263 * @param[in] cb The callback to be called 264 * @param[in] data The data to pass to the callback 265 * @return #EINA_TRUE on success, otherwise #EINA_FALSE 266 */ 267 EAPI Eina_Bool eina_file_dir_list(const char *dir, 268 Eina_Bool recursive, 269 Eina_File_Dir_List_Cb cb, 270 void *data) EINA_ARG_NONNULL(1, 3); 271 272 /** 273 * @brief Splits a path according to the delimiter of the filesystem. 274 * @details This function splits @p path according to the delimiter of the used 275 * filesystem. If @p path is @c NULL or if the array cannot be 276 * created, @c NULL is returned, otherwise an array with each part of @p path 277 * is returned. 278 * 279 * @param[in] path The path to split 280 * @return An array of the parts of the path to split 281 * 282 */ 283 EAPI Eina_Array *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; 284 285 /** 286 * @brief Gets an iterator to list the content of a directory. 287 * @details This returns an iterator for shared strings, the name of each file in @p dir is 288 * only fetched when advancing the iterator, which means there is very little 289 * cost associated with creating the list and stopping halfway through it. 290 * 291 * @param[in] dir The name of the directory to list 292 * @return An #Eina_Iterator that walks over the files and directories 293 * in @p dir. On failure, it returns @c NULL. 294 * 295 * @note The iterator hands the user a stringshared value with the full 296 * path. The user must free the string using eina_stringshare_del() on it. 297 * 298 * @note The container for the iterator is of type DIR*. 299 * @note The iterator walks over '.' and '..' without returning them. 300 * 301 * @see eina_file_direct_ls() 302 */ 303 EAPI Eina_Iterator *eina_file_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; 304 305 /** 306 * @brief Gets an iterator to list the content of a directory, with direct 307 * information. 308 * @details This returns an iterator for #Eina_File_Direct_Info, the name of each file in @p 309 * dir is only fetched when advancing the iterator, which means there is 310 * cost associated with creating the list and stopping halfway through it. 311 * 312 * @param[in] dir The name of the directory to list 313 * 314 * @return An #Eina_Iterator that walks over the files and 315 * directories in @p dir. On failure, it returns @c NULL. 316 * 317 * @warning The #Eina_File_Direct_Info returned by the iterator <b>must not</b> 318 * be modified in any way. 319 * @warning When the iterator is advanced or deleted the #Eina_File_Direct_Info 320 * returned is no longer valid. 321 * 322 * @note The container for the iterator is of type DIR*. 323 * @note The iterator walks over '.' and '..' without returning them. 324 * @note The difference between this function and eina_file_direct_ls() is that 325 * it guarantees the file type information to be correct by incurring a 326 * possible performance penalty. 327 * 328 * @see eina_file_direct_ls() 329 */ 330 EAPI Eina_Iterator *eina_file_stat_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; 331 332 /** 333 * @brief Uses information provided by #Eina_Iterator of eina_file_stat_ls() or eina_file_direct_ls() 334 * to call stat in the most efficient way on your system. 335 * @details This function calls fstatat or stat depending on what your system supports. This makes it efficient and simple 336 * to use on your side without complex detection already done inside Eina on what the system can do. 337 * 338 * @param[in] container The container returned by #Eina_Iterator using eina_iterator_container_get() 339 * @param[in] info The content of the current #Eina_File_Direct_Info provided by #Eina_Iterator 340 * @param[in] buf The location put the result of the stat 341 * @return @c 0 is returned on success, otherwise @c -1 is returned on error and errno is set appropriately 342 * 343 * @see eina_file_direct_ls() 344 * @see eina_file_stat_ls() 345 * 346 * @since 1.2 347 */ 348 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); 349 350 /** 351 * @brief Close all file descriptors that are open at or above the given fd 352 * @details This closes all open file descriptors that are equal to or of 353 * higher value than the given inpit fd given. This is intended for 354 * niche use like closing all open files just before exec()ing a 355 * new process after calling fork(). The except_fd array can be NULL 356 * if no fd's are to be skipped, but if some fd's are to skip being 357 * closed then this will be an array of fd numbers being terminated 358 * by a fd value of -1. 359 * 360 * @param[in] fd The fd value to begin closing at 361 * @param[in] except_fd An array of fd's not to close terminated by -1 as the last invalid fd 362 * 363 * @since 1.24 364 */ 365 EAPI void eina_file_close_from(int fd, int *except_fd); 366 367 /** 368 * @brief Generates and creates a uniquely named temporary file from a template name. 369 * The generated file is opened with the open(2) @c O_EXCL flag. 370 * @details This function calls mkstemp(), generates a unique temporary filename 371 * from template, creates and opens the file, and returns an open file 372 * descriptor for the file. 373 * 374 * @param[in] templatename This is a string. It must contain the six characters 'XXXXXX' 375 * at the end or directly followed by an extension as in 376 * 'prefixXXXXXX.ext'. 377 * @param[out] path The path to the created temporary file, or @c NULL in case of failure. 378 * It must be released by eina_tmpstr_del(). 379 * @return On success @c file descriptor of the temporary file is returned, 380 * On error @c -1 is returned, in which case @c errno is set appropriately. 381 * 382 * @note If a filename extension was specified in @p templatename, then the new @p path 383 * will also contain this extension (since 1.10). 384 * 385 * @note If the @p templatename is a simple file name (no relative or absolute 386 * path to another directory), then a temporary file will be created inside 387 * the system temporary directory (@see eina_environment_tmp_get()). If the 388 * @p templatename contains a directory separator ('/', or '\\' on Windows) 389 * then the file will be created inside this directory, which must exist and 390 * be writeable. Use ./filename.XXXXXX to create files in the current 391 * working directory. (since 1.17) 392 * 393 * @see eina_file_mkdtemp() 394 * @since 1.8 395 */ 396 EAPI int eina_file_mkstemp(const char *templatename, Eina_Tmpstr **path) EINA_ARG_NONNULL(1); 397 398 /** 399 * @brief Generates and creates a uniquely named temporary directory from a template name. 400 * @details This function calls mkdtemp(). The directory is then created with 401 * permissions 0700. 402 * 403 * @param[in] templatename This is a string. The last six characters of @p templatename 404 * must be XXXXXX. 405 * @param[out] path The path to the created temporary directory, or @c NULL in case of failure. 406 * It must be released by eina_tmpstr_del(). 407 * @return On success @c EINA_TRUE is returned, On error @c EINA_FALSE is returned, 408 * in which case @c errno is set appropriately. 409 * 410 * @note If the @p templatename is a simple directory name (no relative or absolute 411 * path to another directory), then a temporary directory will be created inside 412 * the system temporary directory (@see eina_environment_tmp_get()). If the 413 * @p templatename contains a directory separator ('/', or '\\' on Windows) 414 * then the temporary directory will be created inside that other directory, 415 * which must exist and be writeable. (since 1.17) 416 * 417 * @see eina_file_mkstemp() 418 * @since 1.8 419 */ 420 EAPI Eina_Bool eina_file_mkdtemp(const char *templatename, Eina_Tmpstr **path) EINA_ARG_NONNULL(1,2); 421 422 /** 423 * @brief Gets an iterator to list the content of a directory, with direct 424 * information. 425 * @details This returns an iterator for #Eina_File_Direct_Info, the name of each file in 426 * @p dir is only fetched when advancing the iterator, which means there is 427 * cost associated with creating the list and stopping halfway through it. 428 * 429 * @param[in] dir The name of the directory to list 430 * 431 * @return An Eina_Iterator that walks over the files and 432 * directories in @p dir. On failure, it returns @c NULL. 433 * 434 * @warning If readdir_r doesn't contain file type information, file type is 435 * EINA_FILE_UNKNOWN. 436 * @warning The #Eina_File_Direct_Info returned by the iterator <b>must not</b> 437 * be modified in any way. 438 * @warning When the iterator is advanced or deleted the #Eina_File_Direct_Info 439 * returned is no longer valid. 440 * 441 * @note The container for the iterator is of type DIR*. 442 * @note The iterator walks over '.' and '..' without returning them. 443 * @note The difference between this function and eina_file_stat_ls() is that 444 * it may not get the file type information however it is likely to be 445 * faster. 446 * 447 * @see eina_file_ls() 448 */ 449 EAPI Eina_Iterator *eina_file_direct_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; 450 451 /** 452 * @brief Sanitizes the file path. 453 * @details This function takes care of adding the current working directory if its a 454 * relative path and also removes all '..' and '//' references in the original 455 * path. 456 * 457 * @param[in] path The path to sanitize 458 * 459 * @return An allocated string with the sanitized path 460 * 461 * @since 1.1 462 */ 463 EAPI char *eina_file_path_sanitize(const char *path); 464 465 /** 466 * @typedef Eina_File_Copy_Progress 467 * @brief Type for a callback to report file copy progress. 468 * @details This function is used to report progress during eina_file_copy(), where @p done 469 * is the bytes already copied and @c size is the total file size. 470 * 471 * @note If it returns #EINA_FALSE, it will stop the copy. 472 */ 473 typedef Eina_Bool (*Eina_File_Copy_Progress)(void *data, unsigned long long done, unsigned long long total); 474 475 /** 476 * @typedef Eina_File_Copy_Flags 477 * @brief Enumeration for a flag what to copy from file. 478 */ 479 typedef enum { 480 EINA_FILE_COPY_DATA = 0, 481 EINA_FILE_COPY_PERMISSION = (1 << 0), 482 EINA_FILE_COPY_XATTR = (1 << 1) 483 } Eina_File_Copy_Flags; 484 485 /** 486 * @brief Copies one file to another using the fastest possible way and report progress. 487 * @details This function tries to splice if it is available. It is blocked 488 * until the whole file is copied or it fails. 489 * 490 * @param[in] src The source file. 491 * @param[in] dst The destination file. 492 * @param[in] flags Controls what is copied (data is always copied). 493 * @param[in] cb If it is provided will be called with file copy progress information. 494 * @param[in] cb_data Context data to provide to @p cb during copy. 495 * @return #EINA_TRUE on success, #EINA_FALSE otherwise (and @p dst 496 * will be deleted) 497 * 498 * @note During the progress it may call back @p cb with the progress summary. 499 */ 500 EAPI Eina_Bool eina_file_copy(const char *src, const char *dst, Eina_File_Copy_Flags flags, Eina_File_Copy_Progress cb, const void *cb_data) EINA_ARG_NONNULL(1, 2); 501 502 /** 503 * @brief Gets a read-only handler to a file. 504 * @details This opens a file in the read-only mode. @p name should be an absolute path. An 505 * #Eina_File handle can be shared among multiple instances if @p shared 506 * is #EINA_TRUE, otherwise. 507 * 508 * @param[in] name The filename to open 509 * @param[in] shared Requested a shm 510 511 * @return An #Eina_File handle to the file 512 * 513 * @since 1.1 514 */ 515 EAPI Eina_File *eina_file_open(const char *name, Eina_Bool shared) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; 516 517 /** 518 * @brief Creates a virtual file from a memory pointer. 519 * 520 * @param[in] virtual_name A virtual name for Eina_File, if @c NULL, a generated one will be given 521 * @param[in] data The memory pointer to take data from 522 * @param[in] length The length of the data in memory 523 * @param[in] copy #EINA_TRUE if the data must be copied 524 * @return #Eina_File handle to the file 525 * 526 * @since 1.8 527 */ 528 EAPI Eina_File * 529 eina_file_virtualize(const char *virtual_name, const void *data, unsigned long long length, Eina_Bool copy) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 530 531 /** 532 * @brief Tells if a file is a real file or only exists in memory. 533 * 534 * @param[in] file The file to test 535 * @return #EINA_TRUE if the file is a virtual file 536 * 537 * @since 1.8 538 */ 539 EAPI Eina_Bool 540 eina_file_virtual(Eina_File *file) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 541 542 /** 543 * @brief Refreshes file information. 544 * @details All current map continue to exist. You need to manually delete 545 * and recreate them to have the new correct mapping. 546 * 547 * @param[in,out] file The file to refresh 548 * @return #EINA_TRUE if the file has changed 549 * 550 * @since 1.8 551 */ 552 EAPI Eina_Bool eina_file_refresh(Eina_File *file); 553 554 /** 555 * @brief Duplicates a read-only handler of a previously open file. 556 * 557 * @param[in] file To duplicate a reference to 558 * @return #Eina_File handle of the duplicated file 559 * 560 * @note Opens a file in read-only mode. 561 * 562 * @since 1.8 563 */ 564 EAPI Eina_File * eina_file_dup(const Eina_File *file); 565 566 /** 567 * @brief Unrefs the file handler. 568 * @details This decrements the file's reference count and if it reaches zero it closes the file. 569 * 570 * @param[in] file The file handler to unref 571 * 572 * @since 1.1 573 */ 574 EAPI void eina_file_close(Eina_File *file); 575 576 /** 577 * @brief Gets the file size at open time. 578 * 579 * @param[in] file The file handler to request the size from 580 * @return The length of the file 581 * 582 * @since 1.1 583 */ 584 EAPI size_t eina_file_size_get(const Eina_File *file); 585 586 /** 587 * @brief Gets the last modification time of an open file. 588 * 589 * @param[in] file The file handler to request the modification time from 590 * @return The last modification time 591 * 592 * @since 1.1 593 */ 594 EAPI time_t eina_file_mtime_get(const Eina_File *file); 595 596 /** 597 * @brief Gets the filename of an open file. 598 * 599 * @param[in] file The file handler to request the name from 600 * @return The stringshared filename of the file 601 * 602 * @since 1.1 603 */ 604 EAPI const char *eina_file_filename_get(const Eina_File *file); 605 606 /** 607 * @brief Gets the extended attribute of an open file. 608 * 609 * @param[in] file The file handler to request the extended attribute from 610 * @return An iterator 611 * 612 * @note The iterator lists all the extended attribute names without allocating 613 * them, so you need to copy them yourself if needed. 614 * 615 * @since 1.2 616 */ 617 EAPI Eina_Iterator *eina_file_xattr_get(Eina_File *file); 618 619 /** 620 * @brief Gets the extended attribute of an open file. 621 * 622 * @param[in] file The file handler to request the extended attribute from 623 * @return An iterator 624 * 625 * @note The iterator lists all the extended attribute names without allocating 626 * them, so you need to copy them yourself if needed. It returns the 627 * Eina_Xattr structure. 628 * 629 * @since 1.2 630 */ 631 EAPI Eina_Iterator *eina_file_xattr_value_get(Eina_File *file); 632 633 /** 634 * @brief Maps all the files to a buffer. 635 * 636 * @param[in] file The file handler to map in the memory 637 * @param[in] rule The rule to apply to the mapped memory 638 * @return A pointer to a buffer that maps all the file content \n 639 * @c NULL if it fails 640 * 641 * @since 1.1 642 */ 643 EAPI void *eina_file_map_all(Eina_File *file, Eina_File_Populate rule); 644 645 /** 646 * @brief Maps a part of the file. 647 * 648 * @param[in] file The file handler to map in the memory 649 * @param[in] rule The rule to apply to the mapped memory 650 * @param[in] offset The offset inside the file 651 * @param[in] length The length of the memory to map 652 * @return A valid pointer to the system memory with @p length valid bytes in it \n 653 * And @c NULL if not inside the file or anything else goes wrong. 654 * 655 * @note This does handle reference counting so it can share the same memory area. 656 * 657 * @since 1.1 658 */ 659 EAPI void *eina_file_map_new(Eina_File *file, Eina_File_Populate rule, 660 unsigned long int offset, unsigned long int length); 661 662 /** 663 * @brief Unrefs and unmaps memory if possible. 664 * 665 * @param[in] file The file handler to unmap memory from 666 * @param[in] map The memory map to unref and unmap 667 * 668 * @since 1.1 669 */ 670 EAPI void eina_file_map_free(Eina_File *file, void *map); 671 672 /** 673 * @brief Asks the OS to populate or otherwise pages of memory in file mapping. 674 * @details This advises the operating system as to what to do with the memory mapped 675 * to the given @p file. This affects a specific range of memory and may not 676 * be honored if the system chooses to ignore the request. 677 * 678 * @param[in] file The file handle from which the map comes 679 * @param[in] rule The rule to apply to the mapped memory 680 * @param[in] map Memory that was mapped inside of which the memory range is 681 * @param[in] offset The offset in bytes from the start of the map address 682 * @param[in] length The length in bytes of the memory region to populate 683 * 684 * @since 1.8 685 */ 686 EAPI void 687 eina_file_map_populate(Eina_File *file, Eina_File_Populate rule, const void *map, 688 unsigned long int offset, unsigned long int length); 689 690 /** 691 * @brief Maps line by line in the memory efficiently using an #Eina_Iterator. 692 * @details This function returns an iterator that acts like fgets without 693 * useless memcpy. Be aware that once eina_iterator_next has been called, 694 * nothing can guarantee that the memory is still going to be mapped. 695 * 696 * @param[in] file The file to run over 697 * @return An Eina_Iterator that produces #Eina_File_Line 698 * 699 * @since 1.3 700 */ 701 EAPI Eina_Iterator *eina_file_map_lines(Eina_File *file); 702 703 /** 704 * @brief Tells whether there has been an IO error during the life of a mmaped file. 705 * 706 * @param[in] file The file handler to the mmaped file 707 * @param[in] map The memory map to check if an error occurred on it 708 * @return #EINA_TRUE if there has been an IO error, otherwise #EINA_FALSE 709 * 710 * @since 1.2 711 */ 712 EAPI Eina_Bool eina_file_map_faulted(Eina_File *file, void *map); 713 714 /** 715 * @brief Joins two paths of known length. 716 * @details This function is similar to eina_str_join_len(), but the separator 717 * is '\' on Windows and '/' otherwise. 718 * 719 * @param[out] dst The buffer to store the result. 720 * @param[in] size Size (in byte) of the buffer. 721 * @param[in] a First path to use. 722 * @param[in] a_len length of @p a. 723 * @param[in] b Second path to use. 724 * @param[in] b_len length of @p b. 725 * @return The number of characters printed. 726 * 727 * @see eina_str_join_len() 728 * @see eina_file_path_join() 729 * 730 * @since 1.16 731 */ 732 static inline size_t eina_file_path_join_len(char *dst, 733 size_t size, 734 const char *a, 735 size_t a_len, 736 const char *b, 737 size_t b_len); 738 739 /** 740 * @brief Joins two paths of known length. 741 * @details This function is similar to eina_file_path_join_len(), but will compute 742 * the length of @p a and @p b using strlen(). The path separator is 743 * '\' on Windows and '/' otherwise. 744 * 745 * @param[out] dst The buffer to store the result. 746 * @param[in] size Size (in byte) of the buffer. 747 * @param[in] a First string to use. 748 * @param[in] b Second string to use. 749 * @return The number of characters printed. 750 * 751 * @see eina_file_path_join_len() 752 * 753 * @since 1.16 754 */ 755 static inline size_t eina_file_path_join(char *dst, 756 size_t size, 757 const char *a, 758 const char *b); 759 760 761 /** 762 * @brief Unlinks file. 763 * @details This function is a wrapper around the unlink() system call. It removes a link to 764 * a file. 765 * 766 * @param[in] pathname File name to unlink. 767 * @return #EINA_TRUE if the unlink was successful, #EINA_FALSE otherwise.. 768 * 769 * @since 1.19 770 */ 771 EAPI Eina_Bool eina_file_unlink(const char *pathname); 772 773 /** 774 * @brief Make sure a file descriptor will be closed on exec. 775 * @details This function is a wrapper around the fnctl() system call. It makes sure 776 * that the fd will be closed whenever exec is called. 777 * 778 * @param[in] fd File descriptor to enforce close on exec on. 779 * @param[in] on #EINA_TRUE will turn close on exec on, #EINA_FALSE will turn it off. 780 * @return #EINA_TRUE if it will be closed on exec, #EINA_FALSE otherwise.. 781 * 782 * @since 1.20 783 */ 784 EAPI Eina_Bool eina_file_close_on_exec(int fd, Eina_Bool on); 785 786 #include "eina_inline_file.x" 787 788 /** 789 * @typedef Eina_Statgen 790 * @brief Stat Generation count state with it being 0 when disabled or some other value that is comparable (== or !=) to a stored value and if it is not equal, then do the actual stat i/o work 791 * @since 1.23 792 */ 793 typedef unsigned int Eina_Statgen; 794 795 /** 796 * @brief Force the stat generation counter to tick over so any following i/o does real i/o and stat calls 797 * @since 1.23 798 */ 799 EAPI void eina_file_statgen_next(void); 800 801 /** 802 * @brief Get the current stat generation counter value 803 * @return 0 if you should always do stat calls and compare, or some other value that changes like a generation counter 804 * @since 1.23 805 */ 806 EAPI Eina_Statgen eina_file_statgen_get(void); 807 808 /** 809 * @brief Enable stat generation count optimiziing to only stat/do file i/o between generation counts changing 810 * @since 1.23 811 */ 812 EAPI void eina_file_statgen_enable(void); 813 814 /** 815 * @brief Disable stat generation count optimiziing to only stat/do file i/o between generation counts changing 816 * @since 1.23 817 */ 818 EAPI void eina_file_statgen_disable(void); 819 820 /** 821 * @} 822 */ 823 824 #endif /* EINA_FILE_H_ */ 825