File
[Tools]

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...

Defines

#define EINA_PATH_MAX   8192
#define EINA_FILE_DIR_LIST_CB(function)   ((Eina_File_Dir_List_Cb)function)
 cast to an Eina_File_Dir_List_Cb.

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.
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.
typedef struct _Eina_File Eina_File

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
}

Functions

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.
Eina_Arrayeina_file_split (char *path)
 Split a path according to the delimiter of the filesystem.
Eina_Iteratoreina_file_ls (const char *dir)
 Get an iterator to list the content of a directory.
Eina_Iteratoreina_file_stat_ls (const char *dir)
 Get an iterator to list the content of a directory, with direct information.
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.
Eina_Iteratoreina_file_direct_ls (const char *dir)
 Get an iterator to list the content of a directory, with direct information.
char * eina_file_path_sanitize (const char *path)
 Sanitize file path.
Eina_File * eina_file_open (const char *name, Eina_Bool shared)
 Get a read-only handler to a file.
void eina_file_close (Eina_File *file)
 Unref file handler.
size_t eina_file_size_get (Eina_File *file)
 Get file size at open time.
time_t eina_file_mtime_get (Eina_File *file)
 Get the last modification time of an open file.
const char * eina_file_filename_get (Eina_File *file)
 Get the filename of an open file.
Eina_Iteratoreina_file_xattr_get (Eina_File *file)
 Get the eXtended attribute of an open file.
Eina_Iteratoreina_file_xattr_value_get (Eina_File *file)
 Get the eXtended attribute of an open file.
void * eina_file_map_all (Eina_File *file, Eina_File_Populate rule)
 Map all the file to a buffer.
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.
void eina_file_map_free (Eina_File *file, void *map)
 Unref and unmap memory if possible.
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.

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.

Define Documentation

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

cast to an Eina_File_Dir_List_Cb.

Parameters:
function The function to cast.
This macro casts function to Eina_File_Dir_List_Cb.


Typedef Documentation

A typedef to _Eina_Stat.

Since:
1.2

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

Parameters:
The file name EXCLUDING the path
path The path passed to eina_file_dir_list()
data The data passed to eina_file_dir_list()


Enumeration Type Documentation

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).

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.


Function Documentation

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:
dir The directory name.
recursive Iterate recursively in the directory.
cb The callback to be called.
data The 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.

References EINA_FALSE, EINA_FILE_DIR, eina_file_dir_list(), eina_file_stat_ls(), EINA_ITERATOR_FOREACH, eina_iterator_free(), EINA_TRUE, _Eina_File_Direct_Info::name_start, _Eina_File_Direct_Info::path, and _Eina_File_Direct_Info::type.

Referenced by eina_file_dir_list(), eina_module_arch_list_get(), and eina_module_list_get().

Eina_Array* eina_file_split ( char *  path  ) 

Split a path according to the delimiter of the filesystem.

Parameters:
path The 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.

References eina_array_new(), and eina_array_push().

Eina_Iterator* eina_file_ls ( const char *  dir  ) 

Get an iterator to list the content of a directory.

Parameters:
dir The 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()

References EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.

Eina_Iterator* eina_file_stat_ls ( const char *  dir  ) 

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

Parameters:
dir The 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 ahd 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 eina_file_direct_ls(), EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.

Referenced by eina_file_dir_list().

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:
container The container returned by the Eina_Iterator.
info The content of the curently Eina_File_Direct_Info provided by the Eina_Iterator
buf Where to put the result of the stat
Returns:
On success 0 is returned, On error -1 is returned and errno is set appropriatly.
This function call fstatat or stat depending on what your system support. This make 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

References _Eina_Stat::atime, _Eina_Stat::atimensec, _Eina_Stat::blksize, _Eina_Stat::blocks, _Eina_Stat::ctime, _Eina_Stat::ctimensec, _Eina_Stat::dev, EINA_FILE_BLK, EINA_FILE_CHR, EINA_FILE_DIR, EINA_FILE_FIFO, EINA_FILE_LNK, EINA_FILE_REG, EINA_FILE_SOCK, EINA_FILE_UNKNOWN, _Eina_Stat::gid, _Eina_Stat::ino, _Eina_Stat::mode, _Eina_Stat::mtime, _Eina_Stat::mtimensec, _Eina_File_Direct_Info::name_start, _Eina_Stat::nlink, _Eina_File_Direct_Info::path, _Eina_Stat::rdev, _Eina_Stat::size, _Eina_File_Direct_Info::type, and _Eina_Stat::uid.

Eina_Iterator* eina_file_direct_ls ( const char *  dir  ) 

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

Parameters:
dir The 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 ahd 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()

References EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.

Referenced by eina_file_stat_ls().

char* eina_file_path_sanitize ( const char *  path  ) 

Sanitize file path.

Parameters:
path The 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

Referenced by eina_file_open().

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

Get a read-only handler to a file.

Parameters:
name Filename to open
shared Requested a shm
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

References EINA_FALSE, eina_file_path_sanitize(), EINA_FREE_CB, eina_hash_del(), eina_hash_direct_add(), eina_hash_find(), eina_hash_new(), eina_hash_pointer_new(), eina_lock_new(), eina_lock_release(), eina_lock_take(), and EINA_TRUE.

void eina_file_close ( Eina_File *  file  ) 

Unref file handler.

Parameters:
file File handler to unref.
Decremente file's refcount and if it reaches zero close it.

Since:
1.1

References eina_hash_del(), eina_lock_release(), and eina_lock_take().

size_t eina_file_size_get ( Eina_File *  file  ) 

Get file size at open time.

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

time_t eina_file_mtime_get ( Eina_File *  file  ) 

Get the last modification time of an open file.

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

const char* eina_file_filename_get ( Eina_File *  file  ) 

Get the filename of an open file.

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

Eina_Iterator* eina_file_xattr_get ( Eina_File *  file  ) 

Get the eXtended attribute of an open file.

Parameters:
file The 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

References eina_xattr_fd_ls().

Eina_Iterator* eina_file_xattr_value_get ( Eina_File *  file  ) 

Get the eXtended attribute of an open file.

Parameters:
file The 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 eina_xattr_value_fd_ls().

void* eina_file_map_all ( Eina_File *  file,
Eina_File_Populate  rule 
)

Map all the file to a buffer.

Parameters:
file The file handler to map in memory
rule The 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

References EINA_FALSE, EINA_FILE_POPULATE, eina_lock_release(), eina_lock_take(), eina_mmap_safety_enabled_set(), and EINA_TRUE.

Referenced by eina_file_map_new().

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:
file The file handler to map in memory
rule The rule to apply to the mapped memory
offset The offset inside the file
length The 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

References EINA_FALSE, eina_file_map_all(), EINA_FILE_POPULATE, eina_hash_add(), eina_hash_direct_add(), eina_hash_find(), eina_lock_release(), eina_lock_take(), eina_mmap_safety_enabled_set(), and EINA_TRUE.

void eina_file_map_free ( Eina_File *  file,
void *  map 
)

Unref and unmap memory if possible.

Parameters:
file The file handler to unmap memory from.
map Memory map to unref and unmap.
Since:
1.1

References eina_hash_del(), eina_hash_find(), eina_lock_release(), and eina_lock_take().

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:
file The file handler to the mmaped file.
map Memory map to check if an error occured on it.
Since:
1.2

References EINA_FALSE, eina_hash_find(), and eina_lock_take().