Tizen Native API  5.5

This group discusses the functions to handle files and directories.

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

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

See an example here.

Functions

Eina_Bool eina_file_dir_list (const char *dir, Eina_Bool recursive, Eina_File_Dir_List_Cb cb, void *data)
 Lists all the files on the directory by calling the function for every file found.
Eina_Arrayeina_file_split (char *path)
 Splits a path according to the delimiter of the filesystem.
Eina_Iteratoreina_file_ls (const char *dir)
 Gets an iterator to list the content of a directory.
Eina_Iteratoreina_file_stat_ls (const char *dir)
 Gets 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)
 Uses 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.
int eina_file_mkstemp (const char *templatename, Eina_Tmpstr **path)
 Close all file descriptors that are open at or above the given fd.
Eina_Bool eina_file_mkdtemp (const char *templatename, Eina_Tmpstr **path)
 Generates and creates a uniquely named temporary directory from a template name.
Eina_Iteratoreina_file_direct_ls (const char *dir)
 Gets an iterator to list the content of a directory, with direct information.
char * eina_file_path_sanitize (const char *path)
 Sanitizes the file path.
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)
 Copies one file to another using the fastest possible way and report progress.
Eina_Fileeina_file_open (const char *name, Eina_Bool shared)
 Gets a read-only handler to a file.
Eina_Fileeina_file_virtualize (const char *virtual_name, const void *data, unsigned long long length, Eina_Bool copy)
 Creates a virtual file from a memory pointer.
Eina_Bool eina_file_virtual (Eina_File *file)
 Tells if a file is a real file or only exists in memory.
Eina_Bool eina_file_refresh (Eina_File *file)
 Refreshes file information.
Eina_Fileeina_file_dup (const Eina_File *file)
 Duplicates a read-only handler of a previously open file.
void eina_file_close (Eina_File *file)
 Unrefs the file handler.
size_t eina_file_size_get (const Eina_File *file)
 Gets the file size at open time.
time_t eina_file_mtime_get (const Eina_File *file)
 Gets the last modification time of an open file.
const char * eina_file_filename_get (const Eina_File *file)
 Gets the filename of an open file.
Eina_Iteratoreina_file_xattr_get (Eina_File *file)
 Gets the extended attribute of an open file.
Eina_Iteratoreina_file_xattr_value_get (Eina_File *file)
 Gets the extended attribute of an open file.
void * eina_file_map_all (Eina_File *file, Eina_File_Populate rule)
 Maps all the files to a buffer.
void * eina_file_map_new (Eina_File *file, Eina_File_Populate rule, unsigned long int offset, unsigned long int length)
 Maps a part of the file.
void eina_file_map_free (Eina_File *file, void *map)
 Unrefs and unmaps memory if possible.
void eina_file_map_populate (Eina_File *file, Eina_File_Populate rule, const void *map, unsigned long int offset, unsigned long int length)
 Asks the OS to populate or otherwise pages of memory in file mapping.
Eina_Iteratoreina_file_map_lines (Eina_File *file)
 Maps line by line in the memory efficiently using an Eina_Iterator.
Eina_Bool eina_file_map_faulted (Eina_File *file, void *map)
 Tells whether there has been an IO error during the life of a mmaped file.
static size_t eina_file_path_join_len (char *dst, size_t size, const char *a, size_t a_len, const char *b, size_t b_len)
 Joins two paths of known length.
static size_t eina_file_path_join (char *dst, size_t size, const char *a, const char *b)
 Joins two paths of known length.

Typedefs

typedef struct
_Eina_File_Direct_Info 
Eina_File_Direct_Info
 A type for _Eina_File_Direct_Info.
typedef struct _Eina_Stat Eina_Stat
 A type for _Eina_Stat.
typedef struct _Eina_File_Line Eina_File_Line
 A type for _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.
typedef struct _Eina_File Eina_File
 A file handle.
typedef Eina_Bool(* Eina_File_Copy_Progress )(void *data, unsigned long long done, unsigned long long total)
 Type for a callback to report file copy progress.
typedef unsigned int Eina_Statgen
 Unlinks file.

Defines

#define EINA_PATH_MAX   8192
 Definition for the constant defined as the highest value for PATH_MAX.
#define EINA_PATH_SEP_C   '/'
 The constant defined the path separator as the character '\' on Windows and '/' otherwise.
#define EINA_PATH_SEP_S   "/"
 The constant defined the path separator as the string "\" on Windows and "/" otherwise.
#define EINA_FILE_DIR_LIST_CB(function)   ((Eina_File_Dir_List_Cb)function)
 The macro to cast to an Eina_File_Dir_List_Cb.

Define Documentation

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

The macro to cast to an Eina_File_Dir_List_Cb.

This macro casts function to Eina_File_Dir_List_Cb.

Parameters:
[in]functionThe function to cast
#define EINA_PATH_SEP_C   '/'

The constant defined the path separator as the character '\' on Windows and '/' otherwise.

Since (EFL) :
1.16
#define EINA_PATH_SEP_S   "/"

The constant defined the path separator as the string "\" on Windows and "/" otherwise.

Since:
1.16

Typedef Documentation

Type for a callback to report file copy progress.

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

Note:
If it returns EINA_FALSE, it will stop the copy.

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

Parameters:
[in]nameThe file name EXCLUDING the path
[in]pathThe path passed to eina_file_dir_list()
[in]dataThe data passed to eina_file_dir_list()

A type for _Eina_Stat.

Since (EFL) :
1.2

Unlinks file.

This function is a wrapper around the unlink() system call. It removes a link to a file.

Parameters:
[in]pathnameFile name to unlink.
Returns:
EINA_TRUE if the unlink was successful, EINA_FALSE otherwise..
Since:
1.19 Make sure a file descriptor will be closed on exec.

This function is a wrapper around the fnctl() system call. It makes sure that the fd will be closed whenever exec is called.

Parameters:
[in]fdFile descriptor to enforce close on exec on.
[in]onEINA_TRUE will turn close on exec on, EINA_FALSE will turn it off.
Returns:
EINA_TRUE if it will be closed on exec, EINA_FALSE otherwise..
Since:
1.20

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

Since:
1.23

Enumeration Type Documentation

Type for enumeration of a file access type.

This type is 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 for 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 (EFL) :
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 succeed if the filesystem does not support it.

Since (EFL) :
1.8

Type for enumeration of a file type.

This type is used 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 (unused on Windows)

EINA_FILE_SOCK 

UNIX domain socket type (unused on Windows)

EINA_FILE_WHT 

Whiteout file type (unused on Windows)


Function Documentation

void eina_file_close ( Eina_File file)

Unrefs the file handler.

This decrements the file's reference count and if it reaches zero it closes the file.

Parameters:
[in]fileThe file handler to unref
Since:
1.1 3.0f(2.3.1)
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 
)

Copies one file to another using the fastest possible way and report progress.

This function tries to splice if it is available. It is blocked until the whole file is copied or it fails.

Parameters:
[in]srcThe source file.
[in]dstThe destination file.
[in]flagsControls what is copied (data is always copied).
[in]cbIf it is provided will be called with file copy progress information.
[in]cb_dataContext data to provide to cb during copy.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise (and dst will be deleted)
Note:
During the progress it may call back cb with the progress summary. 3.0f(2.3.1)
Eina_Bool eina_file_dir_list ( const char *  dir,
Eina_Bool  recursive,
Eina_File_Dir_List_Cb  cb,
void *  data 
)

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

This function calls cb for each file that is in dir. To have cb called on the 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 are operated on, if recursive is EINA_TRUE the entire tree of files that is below dir is operated on.

If cb or dir is NULL or if dir is a string of size 0, or if dir cannot be opened, this function returns EINA_FALSE immediately. Otherwise, it returns EINA_TRUE.

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

3.0

Examples:
eina_file_01.c.
Eina_Iterator* eina_file_direct_ls ( const char *  dir)

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

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

Parameters:
[in]dirThe name of the directory to list
Returns:
An Eina_Iterator that walks over the files and directories in dir. On failure, it returns NULL.
Warning:
If readdir_r doesn't contain file type information, file type is EINA_FILE_UNKNOWN.
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 walks 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() 3.0f(2.3.1)
Examples:
eina_file_01.c.
Eina_File* eina_file_dup ( const Eina_File file)

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

Parameters:
[in]fileTo duplicate a reference to
Returns:
Eina_File handle of the duplicated file
Note:
Opens a file in read-only mode.
Since:
1.8 3.0f(2.3.1)
const char* eina_file_filename_get ( const Eina_File file)

Gets the filename of an open file.

Parameters:
[in]fileThe file handler to request the name from
Returns:
The stringshared filename of the file
Since:
1.1 3.0f(2.3.1)
Eina_Iterator* eina_file_ls ( const char *  dir)

Gets an iterator to list the content of a directory.

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

Parameters:
[in]dirThe name of the directory to list
Returns:
An Eina_Iterator that walks over the files and directories in dir. On failure, it returns NULL.
Note:
The iterator hands the user a stringshared value with the full path. The user must free the string using eina_stringshare_del() on it.
The container for the iterator is of type DIR*.
The iterator walks over '.' and '..' without returning them.
See also:
eina_file_direct_ls() 3.0f(2.3.1)
Examples:
ecore_thread_example.c, and eina_file_01.c.
void* eina_file_map_all ( Eina_File file,
Eina_File_Populate  rule 
)

Maps all the files to a buffer.

Parameters:
[in]fileThe file handler to map in the memory
[in]ruleThe rule to apply to the mapped memory
Returns:
A pointer to a buffer that maps all the file content
NULL if it fails
Since:
1.1 3.0f(2.3.1)
Eina_Bool eina_file_map_faulted ( Eina_File file,
void *  map 
)

Tells whether there has been an IO error during the life of a mmaped file.

Parameters:
[in]fileThe file handler to the mmaped file
[in]mapThe memory map to check if an error occurred on it
Returns:
EINA_TRUE if there has been an IO error, otherwise EINA_FALSE
Since:
1.2 3.0f(2.3.1)
void eina_file_map_free ( Eina_File file,
void *  map 
)

Unrefs and unmaps memory if possible.

Parameters:
[in]fileThe file handler to unmap memory from
[in]mapThe memory map to unref and unmap
Since:
1.1 3.0f(2.3.1)

Maps line by line in the memory efficiently using an Eina_Iterator.

This function returns an iterator that acts like fgets without useless memcpy. Be aware that once eina_iterator_next has been called, nothing can guarantee that the memory is still going to be mapped.

Parameters:
[in]fileThe file to run over
Returns:
An Eina_Iterator that produces Eina_File_Line
Since:
1.3 3.0f(2.3.1)
void* eina_file_map_new ( Eina_File file,
Eina_File_Populate  rule,
unsigned long int  offset,
unsigned long int  length 
)

Maps a part of the file.

Parameters:
[in]fileThe file handler to map in the memory
[in]ruleThe rule to apply to the mapped memory
[in]offsetThe offset inside the file
[in]lengthThe length of the memory to map
Returns:
A valid pointer to the system memory with length valid bytes in it
And NULL if not inside the file or anything else goes wrong.
Note:
This does handle reference counting so it can share the same memory area.
Since:
1.1 3.0f(2.3.1)
void eina_file_map_populate ( Eina_File file,
Eina_File_Populate  rule,
const void *  map,
unsigned long int  offset,
unsigned long int  length 
)

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

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.

Parameters:
[in]fileThe file handle from which the map comes
[in]ruleThe rule to apply to the mapped memory
[in]mapMemory that was mapped inside of which the memory range is
[in]offsetThe offset in bytes from the start of the map address
[in]lengthThe length in bytes of the memory region to populate
Since:
1.8 3.0f(2.3.1)
Eina_Bool eina_file_mkdtemp ( const char *  templatename,
Eina_Tmpstr **  path 
)

Generates and creates a uniquely named temporary directory from a template name.

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

Parameters:
[in]templatenameThis is a string. The last six characters of templatename must be XXXXXX.
[out]pathThe path to the created temporary directory, or NULL in case of failure. It must 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.
Note:
If the templatename is a simple directory name (no relative or absolute path to another directory), then a temporary directory will be created inside the system temporary directory (
See also:
eina_environment_tmp_get()). If the templatename contains a directory separator ('/', or '\' on Windows) then the temporary directory will be created inside that other directory, which must exist and be writeable. (since 1.17)
eina_file_mkstemp()
Since:
1.8 3.0f(2.3.1)
int eina_file_mkstemp ( const char *  templatename,
Eina_Tmpstr **  path 
)

Close all file descriptors that are open at or above the given fd.

This closes all open file descriptors that are equal to or of higher value than the given inpit fd given. This is intended for niche use like closing all open files just before exec()ing a new process after calling fork(). The except_fd array can be NULL if no fd's are to be skipped, but if some fd's are to skip being closed then this will be an array of fd numbers being terminated by a fd value of -1.

Parameters:
[in]fdThe fd value to begin closing at
[in]except_fdAn array of fd's not to close terminated by -1 as the last invalid fd
Since:
1.24 Generates and creates a uniquely named temporary file from a template name. The generated file is opened with the open(2) O_EXCL flag.

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.

Parameters:
[in]templatenameThis is a string. It must contain the six characters 'XXXXXX' at the end or directly followed by an extension as in 'prefixXXXXXX.ext'.
[out]pathThe path to the created temporary file, or NULL in case of failure. It must 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.
Note:
If a filename extension was specified in templatename, then the new path will also contain this extension (since 1.10).
If the templatename is a simple file name (no relative or absolute path to another directory), then a temporary file will be created inside the system temporary directory (
See also:
eina_environment_tmp_get()). If the templatename contains a directory separator ('/', or '\' on Windows) then the file will be created inside this directory, which must exist and be writeable. Use ./filename.XXXXXX to create files in the current working directory. (since 1.17)
eina_file_mkdtemp()
Since:
1.8 3.0f(2.3.1)
time_t eina_file_mtime_get ( const Eina_File file)

Gets the last modification time of an open file.

Parameters:
[in]fileThe file handler to request the modification time from
Returns:
The last modification time
Since:
1.1 3.0f(2.3.1)
Eina_File* eina_file_open ( const char *  name,
Eina_Bool  shared 
)

Gets a read-only handler to a file.

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

Parameters:
[in]nameThe filename to open
[in]sharedRequested a shm
Returns:
An Eina_File handle to the file
Since:
1.1 3.0f(2.3.1)
static size_t eina_file_path_join ( char *  dst,
size_t  size,
const char *  a,
const char *  b 
) [static]

Joins two paths of known length.

This function is similar to eina_file_path_join_len(), but will compute the length of a and b using strlen(). The path separator is '\' on Windows and '/' otherwise.

Parameters:
[out]dstThe buffer to store the result.
[in]sizeSize (in byte) of the buffer.
[in]aFirst string to use.
[in]bSecond string to use.
Returns:
The number of characters printed.
See also:
eina_file_path_join_len()
Since:
1.16
static size_t eina_file_path_join_len ( char *  dst,
size_t  size,
const char *  a,
size_t  a_len,
const char *  b,
size_t  b_len 
) [static]

Joins two paths of known length.

This function is similar to eina_str_join_len(), but the separator is '\' on Windows and '/' otherwise.

Parameters:
[out]dstThe buffer to store the result.
[in]sizeSize (in byte) of the buffer.
[in]aFirst path to use.
[in]a_lenlength of a.
[in]bSecond path to use.
[in]b_lenlength of b.
Returns:
The number of characters printed.
See also:
eina_str_join_len()
eina_file_path_join()
Since:
1.16
char* eina_file_path_sanitize ( const char *  path)

Sanitizes the file path.

This function takes care of adding the current working directory if its a relative path and also removes all '..' and '//' references in the original path.

Parameters:
[in]pathThe path to sanitize
Returns:
An allocated string with the sanitized path
Since:
1.1 3.0f(2.3.1)

Refreshes file information.

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

Parameters:
[in,out]fileThe file to refresh
Returns:
EINA_TRUE if the file has changed
Since:
1.8 3.0f(2.3.1)
size_t eina_file_size_get ( const Eina_File file)

Gets the file size at open time.

Parameters:
[in]fileThe file handler to request the size from
Returns:
The length of the file
Since:
1.1 3.0f(2.3.1)
Eina_Array* eina_file_split ( char *  path)

Splits a path according to the delimiter of the filesystem.

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

Parameters:
[in]pathThe path to split
Returns:
An array of the parts of the path to split

3.0

Eina_Iterator* eina_file_stat_ls ( const char *  dir)

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

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

Parameters:
[in]dirThe name of the directory to list
Returns:
An Eina_Iterator that walks over the files and directories in dir. On failure, it returns NULL.
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 walks over '.' and '..' without returning them.
The difference between this function and eina_file_direct_ls() is that it guarantees the file type information to be correct by incurring a possible performance penalty.
See also:
eina_file_direct_ls() 3.0f(2.3.1)
Examples:
eina_file_01.c.
int eina_file_statat ( void *  container,
Eina_File_Direct_Info info,
Eina_Stat buf 
)

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

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.

Parameters:
[in]containerThe container returned by Eina_Iterator using eina_iterator_container_get()
[in]infoThe content of the current Eina_File_Direct_Info provided by Eina_Iterator
[in]bufThe location put the result of the stat
Returns:
0 is returned on success, otherwise -1 is returned on error and errno is set appropriately
See also:
eina_file_direct_ls()
eina_file_stat_ls()
Since:
1.2 3.0f(2.3.1)

Tells if a file is a real file or only exists in memory.

Parameters:
[in]fileThe file to test
Returns:
EINA_TRUE if the file is a virtual file
Since:
1.8 3.0f(2.3.1)
Eina_File* eina_file_virtualize ( const char *  virtual_name,
const void *  data,
unsigned long long  length,
Eina_Bool  copy 
)

Creates a virtual file from a memory pointer.

Parameters:
[in]virtual_nameA virtual name for Eina_File, if NULL, a generated one will be given
[in]dataThe memory pointer to take data from
[in]lengthThe length of the data in memory
[in]copyEINA_TRUE if the data must be copied
Returns:
Eina_File handle to the file
Since:
1.8 3.0f(2.3.1)

Gets the extended attribute of an open file.

Parameters:
[in]fileThe file handler to request the extended attribute from
Returns:
An iterator
Note:
The iterator lists all the extended attribute names without allocating them, so you need to copy them yourself if needed.
Since:
1.2 3.0f(2.3.1)

Gets the extended attribute of an open file.

Parameters:
[in]fileThe file handler to request the extended attribute from
Returns:
An iterator
Note:
The iterator lists all the extended attribute names without allocating them, so you need to copy them yourself if needed. It returns the Eina_Xattr structure.
Since:
1.2 3.0f(2.3.1)