Functions to handle files and directories. More...

Data Structures

struct  _Eina_File_Direct_Info
 A structure to store informations of a path. More...
 
struct  _Eina_Stat
 A structure to store informations of a path. More...
 
struct  _Eina_File_Line
 A structure to store information of line. More...
 

Macros

#define EINA_PATH_MAX   8192
 The constant defined as the highest value for PATH_MAX.
 
#define EINA_FILE_DIR_LIST_CB(function)   ((Eina_File_Dir_List_Cb)function)
 cast to an Eina_File_Dir_List_Cb. More...
 

Typedefs

typedef struct _Eina_File_Direct_Info Eina_File_Direct_Info
 A typedef to _Eina_File_Direct_Info.
 
typedef struct _Eina_Stat Eina_Stat
 A typedef to _Eina_Stat. More...
 
typedef struct _Eina_File_Line Eina_File_Line
 
typedef void(* Eina_File_Dir_List_Cb) (const char *name, const char *path, void *data)
 Type for a callback to be called when iterating over the files of a directory. More...
 
typedef struct _Eina_File Eina_File
 
typedef Eina_Bool(* Eina_File_Copy_Progress) (void *data, unsigned long long done, unsigned long long total)
 used to report progress during eina_file_copy(), where done is the bytes already copied and size is the total file size. More...
 

Enumerations

enum  Eina_File_Type {
  EINA_FILE_UNKNOWN,
  EINA_FILE_FIFO,
  EINA_FILE_CHR,
  EINA_FILE_DIR,
  EINA_FILE_BLK,
  EINA_FILE_REG,
  EINA_FILE_LNK,
  EINA_FILE_SOCK,
  EINA_FILE_WHT
}
 file type in Eina_File_Direct_Info. More...
 
enum  Eina_File_Populate {
  EINA_FILE_RANDOM,
  EINA_FILE_SEQUENTIAL,
  EINA_FILE_WILLNEED,
  EINA_FILE_POPULATE,
  EINA_FILE_DONTNEED,
  EINA_FILE_REMOVE
}
 File access type used in Eina_File_Direct_info. More...
 
enum  Eina_File_Copy_Flags {
  EINA_FILE_COPY_DATA = 0,
  EINA_FILE_COPY_PERMISSION = (1 << 0),
  EINA_FILE_COPY_XATTR = (1 << 1)
}
 what to copy from file.
 

Functions

EAPI Eina_Bool eina_file_dir_list (const char *dir, Eina_Bool recursive, Eina_File_Dir_List_Cb cb, void *data) EINA_ARG_NONNULL(1
 List all files on the directory calling the function for every file found. More...
 
EAPI Eina_Bool EAPI Eina_Arrayeina_file_split (char *path) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC
 Split a path according to the delimiter of the filesystem. More...
 
EAPI Eina_Iteratoreina_file_ls (const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC
 Get an iterator to list the content of a directory. More...
 
EAPI Eina_Iteratoreina_file_stat_ls (const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC
 Get an iterator to list the content of a directory, with direct information. More...
 
EAPI int eina_file_statat (void *container, Eina_File_Direct_Info *info, Eina_Stat *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1
 Use information provided by Eina_Iterator of eina_file_stat_ls or eina_file_direct_ls to call stat in the most efficient way on your system. More...
 
EAPI int EAPI int eina_file_mkstemp (const char *templatename, Eina_Tmpstr **path)
 Generate and create a uniquely named temporary file from template. More...
 
EAPI Eina_Bool eina_file_mkdtemp (const char *templatename, Eina_Tmpstr **path)
 Generate and create a uniquely named temporary directory from template. More...
 
EAPI Eina_Iteratoreina_file_direct_ls (const char *dir) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC
 Get an iterator to list the content of a directory, with direct information. More...
 
EAPI char * eina_file_path_sanitize (const char *path)
 Sanitize file path. More...
 
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
 Copy one file to another using the fastest possible way, report progress. More...
 
EAPI Eina_Bool EAPI Eina_Fileeina_file_open (const char *name, Eina_Bool shared) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC
 Get a read-only handler to a file. More...
 
EAPI Eina_Fileeina_file_virtualize (const char *virtual_name, const void *data, unsigned long long length, Eina_Bool copy) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1)
 Create a virtual file from a memory pointer. More...
 
EAPI Eina_Bool eina_file_virtual (Eina_File *file) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1)
 Tell if a file is a real file or only exist in memory. More...
 
EAPI Eina_Bool eina_file_refresh (Eina_File *file)
 Refresh file information. More...
 
EAPI Eina_Fileeina_file_dup (const Eina_File *file)
 Dup a read-only handler of a previously open file. More...
 
EAPI void eina_file_close (Eina_File *file)
 Unref file handler. More...
 
EAPI size_t eina_file_size_get (const Eina_File *file)
 Get file size at open time. More...
 
EAPI time_t eina_file_mtime_get (const Eina_File *file)
 Get the last modification time of an open file. More...
 
EAPI const char * eina_file_filename_get (const Eina_File *file)
 Get the filename of an open file. More...
 
EAPI Eina_Iteratoreina_file_xattr_get (Eina_File *file)
 Get the eXtended attribute of an open file. More...
 
EAPI Eina_Iteratoreina_file_xattr_value_get (Eina_File *file)
 Get the eXtended attribute of an open file. More...
 
EAPI void * eina_file_map_all (Eina_File *file, Eina_File_Populate rule)
 Map all the file to a buffer. More...
 
EAPI void * eina_file_map_new (Eina_File *file, Eina_File_Populate rule, unsigned long int offset, unsigned long int length)
 Map a part of the file. More...
 
EAPI void eina_file_map_free (Eina_File *file, void *map)
 Unref and unmap memory if possible. More...
 
EAPI void eina_file_map_populate (Eina_File *file, Eina_File_Populate rule, const void *map, unsigned long int offset, unsigned long int length)
 Ask the OS to populate or otherwise pages of memory in file mapping. More...
 
EAPI Eina_Iteratoreina_file_map_lines (Eina_File *file)
 
EAPI Eina_Bool eina_file_map_faulted (Eina_File *file, void *map)
 Tell if their was an IO error during the life of a mmaped file. More...
 

Detailed Description

Functions to handle files and directories.

This functions make it easier to do a number o file and directory operations such as getting the list of files in a directory, spliting paths and finding out file size and type.

Warning
All functions in this group are blocking which means they make take a long time to return, use them carefully.

See an example here.

Macro Definition Documentation

◆ EINA_FILE_DIR_LIST_CB

#define EINA_FILE_DIR_LIST_CB (   function)    ((Eina_File_Dir_List_Cb)function)

cast to an Eina_File_Dir_List_Cb.

Parameters
functionThe function to cast.

This macro casts function to Eina_File_Dir_List_Cb.

Typedef Documentation

◆ Eina_Stat

A typedef to _Eina_Stat.

Since
1.2

◆ Eina_File_Dir_List_Cb

Eina_File_Dir_List_Cb

Type for a callback to be called when iterating over the files of a directory.

Parameters
Thefile name EXCLUDING the path
pathThe path passed to eina_file_dir_list()
dataThe data passed to eina_file_dir_list()

◆ Eina_File_Copy_Progress

Eina_File_Copy_Progress

used to report progress during eina_file_copy(), where done is the bytes already copied and size is the total file size.

If returns EINA_FALSE, it will stop the copy.

Enumeration Type Documentation

◆ Eina_File_Type

file type in Eina_File_Direct_Info.

Enumerator
EINA_FILE_UNKNOWN 

Unknown file type.

EINA_FILE_FIFO 

Named pipe (FIFO) type (unused on Windows).

EINA_FILE_CHR 

Character device type (unused on Windows).

EINA_FILE_DIR 

Directory type.

EINA_FILE_BLK 

Block device type (unused on Windows).

EINA_FILE_REG 

Regular file type.

EINA_FILE_LNK 

Symbolic link type.

EINA_FILE_SOCK 

UNIX domain socket type (unused on Windows).

EINA_FILE_WHT 

Whiteout file type (unused on Windows).

◆ Eina_File_Populate

File access type used in Eina_File_Direct_info.

Enumerator
EINA_FILE_RANDOM 

Advise random memory access to the mapped memory.

EINA_FILE_SEQUENTIAL 

Advise sequential memory access to the mapped memory.

EINA_FILE_WILLNEED 

Advise need for all the mapped memory.

EINA_FILE_POPULATE 

Request all the mapped memory.

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
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 suceed if the filesystem does not support it.

Since
1.8

Function Documentation

◆ eina_file_dir_list()

EAPI Eina_Bool eina_file_dir_list ( const char *  dir,
Eina_Bool  recursive,
Eina_File_Dir_List_Cb  cb,
void *  data 
)

List all files on the directory calling the function for every file found.

Parameters
dirThe directory name.
recursiveIterate recursively in the directory.
cbThe callback to be called.
dataThe data to pass to the callback.
Returns
EINA_TRUE on success, EINA_FALSE otherwise.

This function calls cb for each file that is in dir. To have cb called on files that are in subdirectories of dir recursive should be EINA_TRUE. In other words if recursive is EINA_FALSE, only direct children of dir will be operated on, if recursive is EINA_TRUE the entire tree of files that is below dir will be operated on.

If cb or dir are NULL, or if dir is a string of size 0, or if dir can not be opened, this function returns EINA_FALSE immediately. otherwise, it returns EINA_TRUE.

Examples:
eina_file_01.c.

Referenced by eina_module_arch_list_get(), and eina_module_list_get().

◆ eina_file_split()

EAPI Eina_Bool EAPI Eina_Array* eina_file_split ( char *  path)

Split a path according to the delimiter of the filesystem.

Parameters
pathThe path to split.
Returns
An array of the parts of the path to split.

This function splits path according to the delimiter of the used filesystem. If path is NULL or if the array can not be created, NULL is returned, otherwise, an array with each part of path is returned.

◆ eina_file_ls()

EAPI Eina_Iterator* eina_file_ls ( const char *  dir)

Get an iterator to list the content of a directory.

Parameters
dirThe name of the directory to list
Returns
Return an Eina_Iterator that will walk over the files and directories in dir. On failure it will return NULL.

Returns an iterator for shared strings, the name of each file in dir will only be fetched when advancing the iterator, which means there is very little cost associated with creating the list and stopping halfway through it.

Warning
The iterator will hand the user a stringshared value with the full path. The user must free the string using eina_stringshare_del() on it.
Note
The container for the iterator is of type DIR*.
The iterator will walk over '.' and '..' without returning them.
See also
eina_file_direct_ls()

◆ eina_file_stat_ls()

EAPI Eina_Iterator* eina_file_stat_ls ( const char *  dir)

Get an iterator to list the content of a directory, with direct information.

Parameters
dirThe name of the directory to list
Returns
Return an Eina_Iterator that will walk over the files and directory in the pointed directory. On failure it will return NULL.

Returns an iterator for Eina_File_Direct_Info, the name of each file in dir will only be fetched when advancing the iterator, which means there is cost associated with creating the list and stopping halfway through it.

Warning
The Eina_File_Direct_Info returned by the iterator must not be modified in any way.
When the iterator is advanced or deleted the Eina_File_Direct_Info returned is no longer valid.
Note
The container for the iterator is of type DIR*.
The iterator will walk over '.' and '..' without returning them.
The difference between this function and eina_file_direct_ls() is that it guarantees the file type information will be correct incurring a possible performance penalty.
See also
eina_file_direct_ls()

References EAPI, and eina_file_direct_ls().

◆ eina_file_statat()

EAPI int eina_file_statat ( void *  container,
Eina_File_Direct_Info info,
Eina_Stat buf 
)

Use information provided by Eina_Iterator of eina_file_stat_ls or eina_file_direct_ls to call stat in the most efficient way on your system.

Parameters
containerThe container returned by the Eina_Iterator using eina_iterator_container_get().
infoThe content of the current Eina_File_Direct_Info provided by the Eina_Iterator
bufWhere to put the result of the stat
Returns
On success 0 is returned, On error -1 is returned and errno is set appropriately.

This function calls fstatat or stat depending on what your system supports. This makes it efficient and simple to use on your side without complex detection already done inside Eina on what the system can do.

See also
eina_file_direct_ls()
eina_file_stat_ls()
Since
1.2

Referenced by eina_file_map_faulted().

◆ eina_file_mkstemp()

EAPI int EAPI int eina_file_mkstemp ( const char *  templatename,
Eina_Tmpstr **  path 
)

Generate and create a uniquely named temporary file from template.

Generated file is opened with the open(2) O_EXCL flag.

Parameters
[in]templatenameis a string. The last six characters of templatename must be XXXXXX.
[out]pathWhere to put the name of the created file. If not NULL should be released by eina_tmpstr_del.
Returns
On success file descriptor of the temporary file is returned, On error -1 is returned, in which case errno is set appropriately.

This function calls mkstemp, generates a unique temporary filename from template, creates and opens the file, and returns an open file descriptor for the file.

See also
eina_file_mkdtemp()
Since
1.8

◆ eina_file_mkdtemp()

EAPI Eina_Bool eina_file_mkdtemp ( const char *  templatename,
Eina_Tmpstr **  path 
)

Generate and create a uniquely named temporary directory from template.

Parameters
[in]templatenameis a string. The last six characters of templatename must be XXXXXX.
[out]pathWhere to put the name of the created directory. If not NULL should be released by eina_tmpstr_del.
Returns
On success EINA_TRUE is returned, On error EINA_FALSE is returned, in which case errno is set appropriately.

This function calls mkdtemp. The directory is then created with permissions 0700.

See also
eina_file_mkstemp()
Since
1.8

◆ eina_file_direct_ls()

EAPI Eina_Iterator* eina_file_direct_ls ( const char *  dir)

Get an iterator to list the content of a directory, with direct information.

Parameters
dirThe name of the directory to list
Returns
Return an Eina_Iterator that will walk over the files and directory in the pointed directory. On failure it will return NULL.

Returns an iterator for Eina_File_Direct_Info, the name of each file in dir will only be fetched when advancing the iterator, which means there is cost associated with creating the list and stopping halfway through it.

Warning
If readdir_r doesn't contain file type information file type will be DT_UNKNOW.
The Eina_File_Direct_Info returned by the iterator must not be modified in any way.
When the iterator is advanced or deleted the Eina_File_Direct_Info returned is no longer valid.
Note
The container for the iterator is of type DIR*.
The iterator will walk over '.' and '..' without returning them.
The difference between this function and eina_file_stat_ls() is that it may not get the file type information however it is likely to be faster.
See also
eina_file_ls()

Referenced by ecore_file_dir_is_empty(), ecore_file_ls(), edje_available_modules_get(), and eina_file_stat_ls().

◆ eina_file_path_sanitize()

EAPI char* eina_file_path_sanitize ( const char *  path)

Sanitize file path.

Parameters
pathThe path to sanitize
Returns
an allocated string with the sanitized path.

This function take care of adding the current working directory if it's a relative path and also remove all '..' and '//' reference in the original path.

Since
1.1

References EAPI, and eina_tmpstr_strlen().

◆ eina_file_copy()

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 
)

Copy one file to another using the fastest possible way, report progress.

This function will try splice if it is available. It will block until the whole file is copied or it fails.

During the progress it may call back cb with the progress summary.

Parameters
srcthe source file.
dstthe destination file.
flagscontrols what is copied (data is always copied).
cbif provided will be called with file copy progress information.
cb_datacontext data to provide to cb during copy.
Returns
EINA_TRUE on success, EINA_FALSE otherwise (and dst will be deleted)

◆ eina_file_open()

EAPI Eina_Bool EAPI Eina_File* eina_file_open ( const char *  name,
Eina_Bool  shared 
)

Get a read-only handler to a file.

Parameters
nameFilename to open
sharedRequested a shm
Returns
Eina_File handle to the file

Opens a file in read-only mode. name should be an absolute path. An Eina_File handle can be shared among multiple instances if shared is EINA_TRUE.

Since
1.1

Referenced by edje_file_collection_list(), edje_file_data_get(), edje_file_group_exists(), eet_identity_open(), and eet_open().

◆ eina_file_virtualize()

EAPI Eina_File* eina_file_virtualize ( const char *  virtual_name,
const void *  data,
unsigned long long  length,
Eina_Bool  copy 
)

Create a virtual file from a memory pointer.

Parameters
virtual_nameA virtual name for Eina_File, if #NULL, a generated one will be given
dataThe memory pointer to take data from
lengthThe length of the data in memory
copyEINA_TRUE if the data must be copied
Returns
Eina_File handle to the file
Since
1.8

References EAPI, EINA_FREE_CB, eina_hash_new(), eina_hash_pointer_new(), EINA_KEY_CMP, EINA_KEY_HASH, EINA_KEY_LENGTH, and EINA_TRUE.

Referenced by evas_object_image_memfile_set().

◆ eina_file_virtual()

EAPI Eina_Bool eina_file_virtual ( Eina_File file)

Tell if a file is a real file or only exist in memory.

Parameters
fileThe file to test
Returns
EINA_TRUE if the file is a virtual file
Since
1.8

References EAPI, and EINA_FALSE.

◆ eina_file_refresh()

EAPI Eina_Bool eina_file_refresh ( Eina_File file)

Refresh file information.

Parameters
fileThe file to refresh
Returns
EINA_TRUE if the file has changed

All current map continue to exist. You need to manually delete and recreate them to have the new correct mapping.

Since
1.8

References EINA_FALSE.

◆ eina_file_dup()

EAPI Eina_File* eina_file_dup ( const Eina_File file)

Dup a read-only handler of a previously open file.

Parameters
fileTo duplicate a reference to
Returns
Eina_File handle to the duplicated file

Opens a file in read-only mode.

Since
1.8

References EAPI, eina_hash_free(), and EINA_MAGIC_SET.

Referenced by eet_mmap(), and evas_object_image_memfile_set().

◆ eina_file_close()

EAPI void eina_file_close ( Eina_File file)

Unref file handler.

Parameters
fileFile handler to unref.

Decrement file's refcount and if it reaches zero close it.

Since
1.1

References EINA_TRUE.

Referenced by edje_file_collection_list(), edje_file_data_get(), edje_file_group_exists(), eet_identity_open(), eet_open(), and evas_object_image_memfile_set().

◆ eina_file_size_get()

EAPI size_t eina_file_size_get ( const Eina_File file)

Get file size at open time.

Parameters
fileThe file handler to request the size from.
Returns
The length of the file.
Since
1.1

Referenced by eet_identity_open(), eet_mmap(), and eet_open().

◆ eina_file_mtime_get()

EAPI time_t eina_file_mtime_get ( const Eina_File file)

Get the last modification time of an open file.

Parameters
fileThe file handler to request the modification time from.
Returns
The last modification time.
Since
1.1

◆ eina_file_filename_get()

EAPI const char* eina_file_filename_get ( const Eina_File file)

Get the filename of an open file.

Parameters
fileThe file handler to request the name from.
Returns
Stringshared filename of the file.
Since
1.1

Referenced by eet_mmap(), and evas_object_image_source_events_get().

◆ eina_file_xattr_get()

EAPI Eina_Iterator* eina_file_xattr_get ( Eina_File file)

Get the eXtended attribute of an open file.

Parameters
fileThe file handler to request the eXtended attribute from.
Returns
an iterator.

The iterator will list all eXtended attribute name without allocating them, so you need to copy them yourself if needed.

Since
1.2

◆ eina_file_xattr_value_get()

EAPI Eina_Iterator* eina_file_xattr_value_get ( Eina_File file)

Get the eXtended attribute of an open file.

Parameters
fileThe file handler to request the eXtended attribute from.
Returns
an iterator.

The iterator will list all eXtended attribute without allocating them, so you need to copy them yourself if needed. It is returning Eina_Xattr structure.

Since
1.2

References EAPI.

◆ eina_file_map_all()

EAPI void* eina_file_map_all ( Eina_File file,
Eina_File_Populate  rule 
)

Map all the file to a buffer.

Parameters
fileThe file handler to map in memory
ruleThe rule to apply to the mapped memory
Returns
A pointer to a buffer that map all the file content. NULL if it fail.
Since
1.1

Referenced by eet_identity_open(), eet_mmap(), and eet_open().

◆ eina_file_map_new()

EAPI void* eina_file_map_new ( Eina_File file,
Eina_File_Populate  rule,
unsigned long int  offset,
unsigned long int  length 
)

Map a part of the file.

Parameters
fileThe file handler to map in memory
ruleThe rule to apply to the mapped memory
offsetThe offset inside the file
lengthThe length of the memory to map
Returns
A valid pointer to the system memory with length valid byte in it. And NULL if not inside the file or anything else goes wrong.

This does handle refcounting so it will share map that target the same memory area.

Since
1.1

◆ eina_file_map_free()

EAPI void eina_file_map_free ( Eina_File file,
void *  map 
)

Unref and unmap memory if possible.

Parameters
fileThe file handler to unmap memory from.
mapMemory map to unref and unmap.
Since
1.1

Referenced by eet_identity_open().

◆ eina_file_map_populate()

EAPI void eina_file_map_populate ( Eina_File file,
Eina_File_Populate  rule,
const void *  map,
unsigned long int  offset,
unsigned long int  length 
)

Ask the OS to populate or otherwise pages of memory in file mapping.

Parameters
fileThe file handle from which the map comes
mapMemory that was mapped inside of which the memory range is
offsetThe offset in bytes from the start of the map address
lengthThe length in bytes of the memory region to populate

This advises the operating system as to what to do with the memory mapped to the given file. This affects a specific range of memory and may not be honored if the system chooses to ignore the request.

Since
1.8

References EAPI.

◆ eina_file_map_faulted()

EAPI Eina_Bool eina_file_map_faulted ( Eina_File file,
void *  map 
)

Tell if their was an IO error during the life of a mmaped file.

Parameters
fileThe file handler to the mmaped file.
mapMemory map to check if an error occurred on it.
Returns
EINA_TRUE if there was an IO error, EINA_FALSE otherwise.
Since
1.2

References EAPI, EINA_FALSE, eina_file_statat(), and EINA_UNUSED.