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_Array *	eina_file_split (char *path)
	Splits a path according to the delimiter of the filesystem.
Eina_Iterator *	eina_file_ls (const char *dir)
	Gets an iterator to list the content of a directory.
Eina_Iterator *	eina_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)
	Generates and creates a uniquely named temporary file from a template name. The generated file is opened with the open(2) `O_EXCL` flag.
Eina_Bool	eina_file_mkdtemp (const char templatename, Eina_Tmpstr *path)
	Generates and creates a uniquely named temporary directory from a template name.
Eina_Iterator *	eina_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_File *	eina_file_open (const char *name, Eina_Bool shared)
	Gets a read-only handler to a file.
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.
Eina_Bool	eina_file_virtual (Eina_File *file)
	Tells if a file is a real file or only exist in memory.
Eina_Bool	eina_file_refresh (Eina_File *file)
	Refreshes file information.
Eina_File *	eina_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_Iterator *	eina_file_xattr_get (Eina_File *file)
	Gets the extended attribute of an open file.
Eina_Iterator *	eina_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_Iterator *	eina_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.
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.
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:

function The 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

Eina_File_Copy_Progress

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.

Eina_File_Dir_List_Cb

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

Parameters:

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

Eina_Stat

A type for _Eina_Stat.

Since (EFL) :: 1.2

Enumeration Type Documentation

enum Eina_File_Populate

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 suceed if the filesystem does not support it. Since (EFL) : 1.8

enum Eina_File_Type

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
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] file The file handler to unref

Since:: 1.1

3.0

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]	src	The source file.
[in]	dst	The destination file.
[in]	flags	Controls what is copied (data is always copied).
[in]	cb	If it is provided will be called with file copy progress information.
[in]	cb_data	Context 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.0

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

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:

file	To duplicate a reference to

Returns:: Eina_File handle of the duplicated file

Note:: Opens a file in read-only mode.

Since:: 1.8

3.0

const char* eina_file_filename_get ( const Eina_File * file )

Gets the filename of an open file.

Parameters:

[in] file The file handler to request the name from

Returns:: The stringshared filename of the file

Since:: 1.1

3.0

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] dir The 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.0

Examples:: 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]	file	The file handler to map in the memory
[in]	rule	The 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.0

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]	file	The file handler to the mmaped file
[in]	map	The 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.0

void eina_file_map_free	(	Eina_File *	file,
		void *	map
	)

Unrefs and unmaps memory if possible.

Parameters:

[in]	file	The file handler to unmap memory from
[in]	map	The memory map to unref and unmap

Since:: 1.1

3.0

Eina_Iterator* eina_file_map_lines ( Eina_File * file )

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] file The file to run over

Returns:: An Eina_Iterator that produces Eina_File_Line

Since:: 1.3

3.0

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

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 honoured if the system chooses to ignore the request.

Parameters:

[in]	file	The file handle from which the map comes
[in]	rule	The rule to apply to the mapped memory
[in]	map	Memory that was mapped inside of which the memory range is
[in]	offset	The offset in bytes from the start of the map address
[in]		The length in bytes of the memory region to populate

Since:: 1.8

3.0

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]	templatename	This is a string. The last six characters of `templatename` must be XXXXXX.
[out]	path	The 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.0

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

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]	templatename	This is a string. It must contain the six characters 'XXXXXX' at the end or directly followed by an extension as in 'prefixXXXXXX.ext'.
[out]	path	The 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.0

time_t eina_file_mtime_get ( const Eina_File * file )

Gets the last modification time of an open file.

Parameters:

[in] file The file handler to request the modification time from

Returns:: The last modification time

Since:: 1.1

3.0

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]	name	The filename to open
[in]	shared	Requested a shm

Returns:: An Eina_File handle to the file

Since:: 1.1

3.0

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] path The path to sanitize

Returns:: An allocated string with the sanitized path

Since:: 1.1

3.0

Eina_Bool eina_file_refresh ( Eina_File * file )

Refreshes file information.

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

Parameters:

file	The file to refresh

Returns:: EINA_TRUE if the file has changed

Since:: 1.8

3.0

size_t eina_file_size_get ( const Eina_File * file )

Gets the file size at open time.

Parameters:

[in] file The file handler to request the size from

Returns:: The length of the file

Since:: 1.1

3.0

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] path The 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] dir The 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.0

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]	container	The container returned by Eina_Iterator using eina_iterator_container_get()
[in]	info	The content of the current Eina_File_Direct_Info provided by Eina_Iterator
[in]	buf	The 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.0

Eina_Bool eina_file_virtual ( Eina_File * file )

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

Parameters:

file	The file to test

Returns:: EINA_TRUE if the file is a virtual file

Since:: 1.8

3.0

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_name	A virtual name for Eina_File, if `NULL`, a generated one will be given
[in]	data	The memory pointer to take data from
[in]	length	The length of the data in memory
[in]	copy	EINA_TRUE if the data must be copied

Returns:: Eina_File handle to the file

Since:: 1.8

3.0

Eina_Iterator* eina_file_xattr_get ( Eina_File * file )

Gets the extended attribute of an open file.

Parameters:

[in] file The 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.0

Eina_Iterator* eina_file_xattr_value_get ( Eina_File * file )

Gets the extended attribute of an open file.

Parameters:

[in] file The 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.0

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation