Functions to create, destroy and do basic manipulation of Eet_File handles.

This section explains how to use the most basic Eet functions, which are used to work with eet files, read data from them, store it back in or take a look at what entries it contains, without making use of the serialization capabilities explained in Eet Data Serialization.

The following example will serve as an introduction to most, if not all, of these functions.

If you are only using Eet, this is the only header you need to include.

#include <Eet.h>

Now let's create ourselves an eet file to play with. The following function shows step by step how to open a file and write some data in it. First, we define our file handler and some other things we'll put in it.

   Eet_File *ef;
   char buf[1024], *ptr;
   int size, len, i;
   const char *some_strings[] = {
      "And some more strings",
      "spread across several",
      "elements of an array!"
   };
   const char some_data[] =
     "\x1e\xe7\x0f\x42\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x35"
     "\x00\x00\x00\xa0\x00\x00\x00\xa0\x00\x00\x00\x24\x00\x00\x00\x11"
     "\x00\x00\x00\x00\x2f\x6d\x69\x73\x74\x65\x72\x69\x6f\x75\x73\x2f"
     "\x64\x61\x74\x61\x00\x41\x6e\x20\x45\x45\x54\x20\x69\x6e\x73\x69"
     "\x64\x65\x20\x6f\x66\x20\x61\x6e\x20\x45\x45\x54\x21\x0a\x54\x68"
     "\x69\x73\x20\x77\x61\x73\x6e\x27\x74\x20\x72\x65\x61\x6c\x6c\x79"
     "\x20\x75\x73\x65\x66\x75\x6c\x20\x62\x75\x74\x20\x69\x74\x20\x68"
     "\x65\x6c\x70\x65\x64\x20\x74\x6f\x20\x73\x68\x6f\x77\x20\x68\x6f"
     "\x77\x0a\x74\x6f\x20\x75\x73\x65\x20\x65\x65\x74\x5f\x6d\x65\x6d"
     "\x6f\x70\x65\x6e\x5f\x72\x65\x61\x64\x28\x29\x20\x74\x6f\x20\x6f"
     "\x70\x65\x6e\x20\x61\x6e\x20\x65\x65\x74\x20\x66\x69\x6c\x65\x20"
     "\x66\x72\x6f\x6d\x0a\x64\x61\x74\x61\x20\x61\x6c\x72\x65\x61\x64"
     "\x79\x20\x6c\x6f\x61\x64\x65\x64\x20\x69\x6e\x20\x6d\x65\x6d\x6f"
     "\x72\x79\x2e\x0a\x00";

We open a new file in write mode, and if it fails, we just return, since there's not much more we can do about it..

   ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_WRITE);
   if (!ef) return 0;

Now, we need to write some data in our file. For now, strings will suffice, so let's just dump a bunch of them in there.

   strcpy(buf, "Here is a string of data to save!");
   size = eet_write(ef, "/key/to_store/at", buf, sizeof(buf), 1);
   if (!size)
     {
        fprintf(stderr, "Error writing data!\n");
        eet_close(ef);
        return 0;
     }

As you can see, we copied a string into our static buffer, which is a bit bigger than the full length of the string, and then told Eet to write it into the file, compressed, returning the size of the data written into the file. This is all to show that Eet treats data as just data. It doesn't matter what that data represents (for now), it's all just bytes for it. As running the following code will show, we took a string of around 30 bytes and put it in a buffer of 1024 bytes, but the returned size won't be any of those.

   len = strlen(buf);
   printf("strlen() = %d, eet_write() = %d\n", len, size);

Next, we copy into our buffer our set of strings, including their null terminators and write them into the file. No error checking for the sake of brevity. And a call to eet_sync() to make sure all out data is properly written down to disk, even though we haven't yet closed the file.

   ptr = buf;
   for (i = 0; i < 3; i++)
     {
        len = strlen(some_strings[i]) + 1;
        memcpy(ptr, some_strings[i], len);
        ptr += len;
     }
   eet_write(ef, "/several/strings", buf, sizeof(buf), 1);
   eet_sync(ef);

One more write, this time our large array of binary data and... well, I couldn't come up with a valid use of the last set of strings we stored, so let's take it out from the file with eet_delete().

   eet_write(ef, "/some/mysterious/data", some_data, sizeof(some_data) - 1, 1);

   eet_delete(ef, "/several/strings");

Finally, we close the file, saving any changes back to disk and return. Notice how, if there's any error closing the file or saving its contents, the return value from the function will be a false one, which later on will make the program exit with an error code.

   return eet_close(ef) == EET_ERROR_NONE;

Moving onto our main function, we will open the same file and read it back. Trivial, but it'll show how we can do so in more than one way. We'll skip the variable declarations, as they aren't very different from what we've seen already.

We start from the beginning by initializing Eet so things in general work. Forgetting to do so will result in weird results or crashes when calling any eet function, so if you experience something like that, the first thing to look at is whether eet_init() is missing. Then we call our create_eet_file function, described above, to make sure we have something to work with. If the function fails it will return 0 and we just exit, since nothing from here onwards will work anyway.

   eet_init();

   if (!create_eet_file())
     return -1;

Let's take a look now at what entries our file has. For this, we use eet_list(), which will return a list of strings, each being the name of one entry. Since we skipped before, it may be worth noting that list is declared as a char **. The num parameter will, of course, have the number of entries contained in our file. If everything's fine, we'll get our list and print it to the screen, and once done with it, we free the list. That's just the list, not its contents, as they are internal strings used by Eet and trying to free them will surely break things.

   ef = eet_open("/tmp/my_file.eet", EET_FILE_MODE_READ);
   if (!ef) return -1;

   list = eet_list(ef, "*", &num);
   if (list)
     {
        for (i = 0; i < num; i++)
          printf("Key stored: %s\n", list[i]);
        free(list);
     }

Reading back plain data is simple. Just a call to eet_read() with the file to read from, and the name of the entry we are interested in. We get back our data and the passed size parameter will contain the size of it. If the data was stored compressed, it will decompressed first.

   ret = eet_read(ef, "/key/to_store/at", &size);
   if (ret)
     {
        printf("Data read (%i bytes):\n%s\n", size, ret);
        free(ret);
     }

Another simple read for the set of strings from before, except those were deleted, so we should get a NULL return and continue normally.

   ret = eet_read(ef, "/several/strings", &size);
   if (ret)
     {
        printf("More data read (%i bytes):\n%s\n", size, ret);
        free(ret);
     }

Finally, we'll get our binary data in the same way we got the strings. Once again, it makes no difference for Eet what the data is, it's up to us to know how to handle it.

   ret = eet_read(ef, "/some/mysterious/data", &size);
   if (ret)
     {

Now some cheating, we know that this data is an Eet file because, well... we just know it. So we are going to open it and take a look at its insides. For this, eet_open() won't work, as it needs to have a file on disk to read from and all we have is some data in RAM.

So how do we do? One way would be to create a normal file and write down our data, then open it with eet_open(). Another, faster and more efficient if all we want to do is read the file, is to use eet_memopen_read().

        Eet_File *ef2;

        ef2 = eet_memopen_read(ret, size);

As you can see, the size we got from our previous read was put to good use this time. Unlike the first one where all we had were strings, the size of the data read only serves to demonstrate that we are reading back the entire size of our original buf variable.

A little peeking to see how many entries the file has and to make an example of eet_num_entries() to get that number when we don't care about their names.

        num = eet_num_entries(ef2);
        printf("Mysterious data has %d entries\n", num);

More cheating follows. Just like we knew this was an Eet file, we also know what key to read from, and ontop of that we know that the data in it is not compressed. Knowing all this allows us to take some shortcuts.

        printf("Mysterious data:\n%s\n",
               (char *)eet_read_direct(ef2, "/mysterious/data", NULL));

That's a direct print of our data, whatever that data is. We don't want to worry about having to free it later, so we just used eet_direct_read() to tell Eet to gives a pointer to the internal data in the file, without duplicating it. Since we said that data was not compressed, we shouldn't worry about printing garbage to the screen (and yes, we also know the data is yet another string). We also don't care about the size of the data as it was stored in the file, so we passed NULL as the size parameter. One very important note about this, however, is that we don't care about the size parameter because the data in the file contains the null terminator for the string. So when using Eet to store strings this way, it's very important to consider whether you will keep that final null byte, or to always get the size read and do the necessary checks and copies. It's up to the user and the particular use cases to decide how this will be done.

With everything done, close this second file and free the data used to open it. And this is important, we can't free that data until we are done with the file, as Eet is using it. When opening with eet_memopen_read(), the data passed to it must be available for as long as the the file is open.

        eet_close(ef2);

        free(ret);
     }

Finally, we close the first file, shutdown all internal resources used by Eet and leave our main function, thus terminating our program.

   eet_close(ef);

   eet_shutdown();

   return 0;

You can look at the full code of the example here.

Functions
Eet_File *	eet_open (const char *file, Eet_File_Mode mode)
	Opens an eet file on disk, and returns a handle to it.
Eet_File *	eet_mmap (const Eina_File *file)
	Opens an eet file on disk from an Eina_File handle, and returns a handle to it.
Eet_File *	eet_memopen_read (const void *data, size_t size)
Eet_File_Mode	eet_mode_get (Eet_File *ef)
	Gets the mode an Eet_File was opened with.
Eet_Error	eet_close (Eet_File *ef)
	Closes an eet file handle and flush pending writes.
Eet_Error	eet_sync (Eet_File *ef)
	Syncs content of an eet file handle, flushing pending writes.
Eet_Dictionary *	eet_dictionary_get (Eet_File *ef)
	Returns a handle to the shared string dictionary of the Eet file.
int	eet_dictionary_string_check (Eet_Dictionary ed, const char string)
	Checks if a given string comes from a given dictionary.
int	eet_dictionary_count (const Eet_Dictionary *ed)
	Returns the number of strings inside a dictionary.
void *	eet_read (Eet_File ef, const char name, int *size_ret)
	Reads a specified entry from an eet file and return data.
const void *	eet_read_direct (Eet_File ef, const char name, int *size_ret)
	Reads a specified entry from an eet file and return data.
int	eet_write (Eet_File ef, const char name, const void *data, int size, int compress)
	Write a specified entry to an eet file handle.
int	eet_delete (Eet_File ef, const char name)
	Deletes a specified entry from an Eet file being written or re-written.
Eina_Bool	eet_alias (Eet_File ef, const char name, const char *destination, int compress)
	Alias a specific section to another one. Destination may exist or not, no checks are done.
const char *	eet_file_get (Eet_File *ef)
	Retrieves the filename of an Eet_File.
const char *	eet_alias_get (Eet_File ef, const char name)
	Retrieves the destination name of an alias.
char **	eet_list (Eet_File ef, const char glob, int *count_ret)
	Lists all entries in eet file matching shell glob.
Eina_Iterator *	eet_list_entries (Eet_File *ef)
	Returns an iterator that will describe each entry of an Eet_File.
int	eet_num_entries (Eet_File *ef)
	Returns the number of entries in the specified eet file.
Typedefs
typedef enum _Eet_File_Mode	Eet_File_Mode
typedef struct _Eet_File	Eet_File
typedef struct _Eet_Dictionary	Eet_Dictionary
typedef struct _Eet_Entry	Eet_Entry

Typedef Documentation

Eet_Dictionary

Opaque handle that defines a file-backed (mmaped) dictionary of strings.

Eet_Entry

Eet files may contains multiple Entries per file, this handle describe them. You can get that handle from an iterator given by eet_list_entries().

See also:: eet_list_entries()

Since:: 1.8.0

Eet_File

Opaque handle that defines an Eet file (or memory).

This handle will be returned by the functions eet_open() and eet_memopen_read() and is used by every other function that affects the file in any way. When you are done with it, call eet_close() to close it and, if the file was open for writing, write down to disk any changes made to it.

See also:: eet_open(); eet_memopen_read(); eet_close()

typedef enum _Eet_File_Mode Eet_File_Mode

Modes that a file can be opened.

Enumeration Type Documentation

enum _Eet_File_Mode

Modes that a file can be opened.

Enumerator:

EET_FILE_MODE_READ	File is read-only.
EET_FILE_MODE_WRITE	File is write-only.
EET_FILE_MODE_READ_WRITE	File is for both read and write

Function Documentation

Eina_Bool eet_alias	(	Eet_File *	ef,
		const char *	name,
		const char *	destination,
		int	compress
	)

Alias a specific section to another one. Destination may exist or not, no checks are done.

Parameters:

ef	A valid eet file handle opened for writing.
name	Name of the new entry. eg: "/base/file_i_want".
destination	Actual source of the aliased entry eg: "/base/the_real_stuff_i_want".
compress	Compression flags (1 == compress, 0 = don't compress).

Returns:: EINA_TRUE on success, EINA_FALSE on failure.

Name and Destination must not be NULL, otherwise EINA_FALSE will be returned. The equivalent of this would be calling 'ln -s destination name'

Since:: 1.3.3

3.0

const char* eet_alias_get	(	Eet_File *	ef,
		const char *	name
	)

Retrieves the destination name of an alias.

Parameters:

ef	A valid eet file handle opened for writing
name	Name of the entry. eg: "/base/file_i_want"

Returns:: Destination of the alias. eg: "/base/the_real_stuff_i_want", NULL on failure

Name must not be NULL, otherwise NULL will be returned.

Since:: 1.5

3.0

Eet_Error eet_close ( Eet_File * ef )

Closes an eet file handle and flush pending writes.

Parameters:

ef	A valid eet file handle.

Returns:: An eet error identifier.

This function will flush any pending writes to disk if the eet file was opened for write, and free all data associated with the file handle and file, and close the file. If it was opened for read (or read/write), the file handle may still be held open internally for caching purposes. To flush speculatively held eet file handles use eet_clearcache().

If the eet file handle is not valid nothing will be done.

Since:: 1.0.0

See also:: eet_clearcache()

3.0

Examples:: eet-basic.c, eet-data-cipher_decipher.c, eet-data-file_descriptor_01.c, eet-data-file_descriptor_02.c, eet-data-nested.c, eet-data-simple.c, and eet-file.c.

int eet_delete	(	Eet_File *	ef,
		const char *	name
	)

Deletes a specified entry from an Eet file being written or re-written.

Parameters:

ef	A valid eet file handle opened for writing.
name	Name of the entry. eg: "/base/file_i_want".

Returns:: Success or failure of the delete.

This function will delete the specified chunk of data from the eet file and return greater than 0 on success. 0 will be returned on failure.

The eet file handle must be a valid file handle for an eet file opened for writing. If it is not, 0 will be returned and no action will be performed.

Name, must not be NULL, otherwise 0 will be returned.

Since:: 1.0.0

3.0

Examples:: eet-file.c.

int eet_dictionary_count ( const Eet_Dictionary * ed )

Returns the number of strings inside a dictionary.

Parameters:

ed	A valid dictionary handle

Returns:: the number of strings inside a dictionary

Since:: 1.6.0

3.0

Eet_Dictionary* eet_dictionary_get ( Eet_File * ef )

Returns a handle to the shared string dictionary of the Eet file.

Parameters:

ef	A valid eet file handle.

Returns:: A handle to the dictionary of the file

This function returns a handle to the dictionary of an Eet file whose handle is ef, if a dictionary exists. NULL is returned otherwise or if the file handle is known to be invalid.

See also:: eet_dictionary_string_check() to know if given string came from the dictionary or it was dynamically allocated using the Eet_Data_Descriptor_Class instructions.

Since:: 1.0.0

3.0

Examples:: eet-data-file_descriptor_01.c, and eet-data-file_descriptor_02.c.

int eet_dictionary_string_check	(	Eet_Dictionary *	ed,
		const char *	string
	)

Checks if a given string comes from a given dictionary.

Parameters:

ed	A valid dictionary handle
string	A valid 0 byte terminated C string

Returns:: 1 if it is in the dictionary, 0 otherwise

This checks the given dictionary to see if the given string is actually inside that dictionary (i.e. comes from it) and returns 1 if it does. If the dictionary handle is invalid, the string is NULL or the string is not in the dictionary, 0 is returned.

Since:: 1.0.0

3.0

Examples:: eet-data-file_descriptor_01.c, and eet-data-file_descriptor_02.c.

const char* eet_file_get ( Eet_File * ef )

Retrieves the filename of an Eet_File.

Parameters:

ef	A valid eet file handle opened for writing.

Returns:: The stringshared file string opened with eet_open(), or NULL on error

Note:: This function will return NULL for files opened with eet_memopen_read()

Since:: 1.6

3.0

char** eet_list	(	Eet_File *	ef,
		const char *	glob,
		int *	count_ret
	)

Lists all entries in eet file matching shell glob.

Parameters:

ef	A valid eet file handle.
glob	A shell glob to match against.
count_ret	Number of entries found to match.

Returns:: Pointer to an array of strings.

This function will list all entries in the eet file matching the supplied shell glob and return an allocated list of their names, if there are any, and if no memory errors occur.

The eet file handle must be valid and glob must not be NULL, or NULL will be returned and count_ret will be filled with 0.

The calling program must call free() on the array returned, but NOT on the string pointers in the array. They are taken as read-only internals from the eet file handle. They are only valid as long as the file handle is not closed. When it is closed those pointers in the array are now not valid and should not be used.

On success, the array returned will have a list of string pointers that are the names of the entries that matched, and count_ret will have the number of entries in this array placed in it.

Hint: an easy way to list all entries in an eet file is to use a glob value of "*".

Since:: 1.0.0

3.0

Examples:: eet-file.c.

Eina_Iterator* eet_list_entries ( Eet_File * ef )

Returns an iterator that will describe each entry of an Eet_File.

Parameters:

ef	A valid eet file handle.

Returns:: An interator of Eet_Entry.

Since:: 1.8.0

3.0

Eet_File* eet_memopen_read	(	const void *	data,
		size_t	size
	)

Opens an eet file directly from a memory location. The data is not copied, so you must keep it around as long as the eet file is open. There is currently no cache for this kind of Eet_File, so it's reopened every time you use eet_memopen_read.

Parameters:

data	Address of file in memory.
size	Size of memory to be read.

Returns:: A handle to the file.

Files opened this way will always be in read-only mode.

Since:: 1.1.0

3.0

Examples:: eet-file.c.

Eet_File* eet_mmap ( const Eina_File * file )

Opens an eet file on disk from an Eina_File handle, and returns a handle to it.

Parameters:

file	The Eina_File handle to map to an eet file.

Returns:: An opened eet file handle.

This function will open an exiting eet file for reading, and build the directory table in memory and return a handle to the file, if it exists and can be read, and no memory errors occur on the way, otherwise NULL will be returned.

This function can't open file for writing only read only mode is supported for now.

If the same file is opened multiple times, then the same file handle will be returned as eet maintains an internal list of all currently open files. That means opening a file for read only looks in the read only set, and returns a handle to that file handle and increments its reference count. You need to close an eet file handle as many times as it has been opened to maintain correct reference counts.

Since:: 1.8.0

3.0

Eet_File_Mode eet_mode_get ( Eet_File * ef )

Gets the mode an Eet_File was opened with.

Parameters:

ef	A valid eet file handle.

Returns:: The mode ef was opened with.

Since:: 1.0.0

3.0

int eet_num_entries ( Eet_File * ef )

Returns the number of entries in the specified eet file.

Parameters:

ef	A valid eet file handle.

Returns:: Number of entries in ef or -1 if the number of entries cannot be read due to open mode restrictions.

Since:: 1.0.0

3.0

Examples:: eet-file.c.

Eet_File* eet_open	(	const char *	file,
		Eet_File_Mode	mode
	)

Opens an eet file on disk, and returns a handle to it.

Parameters:

file	The file path to the eet file. eg: `"/tmp/file.eet"`.
mode	The mode for opening. Either EET_FILE_MODE_READ, EET_FILE_MODE_WRITE or EET_FILE_MODE_READ_WRITE.

Returns:: An opened eet file handle.

This function will open an exiting eet file for reading, and build the directory table in memory and return a handle to the file, if it exists and can be read, and no memory errors occur on the way, otherwise NULL will be returned.

It will also open an eet file for writing. This will, if successful, delete the original file and replace it with a new empty file, till the eet file handle is closed or flushed. If it cannot be opened for writing or a memory error occurs, NULL is returned.

You can also open the file for read/write. If you then write a key that does not exist it will be created, if the key exists it will be replaced by the new data.

If the same file is opened multiple times, then the same file handle will be returned as eet maintains an internal list of all currently open files. Note that it considers files opened for read only and those opened for read/write and write only as 2 separate sets. Those that do not write to the file and those that do. Eet will allow 2 handles to the same file if they are in the 2 separate lists/groups. That means opening a file for read only looks in the read only set, and returns a handle to that file handle and increments its reference count. If you open a file for read/write or write only it looks in the write set and returns a handle after incrementing the reference count. You need to close an eet file handle as many times as it has been opened to maintain correct reference counts. Files whose modified timestamp or size do not match those of the existing referenced file handles will not be returned and a new handle will be returned instead.

Since:: 1.0.0

3.0

Examples:: eet-basic.c, eet-data-cipher_decipher.c, eet-data-file_descriptor_01.c, eet-data-file_descriptor_02.c, eet-data-nested.c, eet-data-simple.c, and eet-file.c.

void* eet_read	(	Eet_File *	ef,
		const char *	name,
		int *	size_ret
	)

Reads a specified entry from an eet file and return data.

Parameters:

ef	A valid eet file handle opened for reading.
name	Name of the entry. eg: "/base/file_i_want".
size_ret	Number of bytes read from entry and returned.

Returns:: The data stored in that entry in the eet file.

This function finds an entry in the eet file that is stored under the name specified, and returns that data, decompressed, if successful. NULL is returned if the lookup fails or if memory errors are encountered. It is the job of the calling program to call free() on the returned data. The number of bytes in the returned data chunk are placed in size_ret.

If the eet file handle is not valid NULL is returned and size_ret is filled with 0.

See also:: eet_read_cipher()

Since:: 1.0.0

3.0

Examples:: eet-basic.c, and eet-file.c.

const void* eet_read_direct	(	Eet_File *	ef,
		const char *	name,
		int *	size_ret
	)

Reads a specified entry from an eet file and return data.

Parameters:

ef	A valid eet file handle opened for reading.
name	Name of the entry. eg: "/base/file_i_want".
size_ret	Number of bytes read from entry and returned.

Returns:: The data stored in that entry in the eet file.

This function finds an entry in the eet file that is stored under the name specified, and returns that data if not compressed and successful. NULL is returned if the lookup fails or if memory errors are encountered or if the data is compressed. The calling program must never call free() on the returned data. The number of bytes in the returned data chunk are placed in size_ret.

If the eet file handle is not valid NULL is returned and size_ret is filled with 0.

Since:: 1.0.0

3.0

Examples:: eet-file.c.

Eet_Error eet_sync ( Eet_File * ef )

Syncs content of an eet file handle, flushing pending writes.

Parameters:

ef	A valid eet file handle.

Returns:: An eet error identifier.

This function will flush any pending writes to disk. The eet file must be opened for write.

If the eet file handle is not valid nothing will be done.

Since:: 1.2.4

3.0

Examples:: eet-file.c.

int eet_write	(	Eet_File *	ef,
		const char *	name,
		const void *	data,
		int	size,
		int	compress
	)

Write a specified entry to an eet file handle.

Parameters:

ef	A valid eet file handle opened for writing.
name	Name of the entry. eg: "/base/file_i_want".
data	Pointer to the data to be stored.
size	Length in bytes in the data to be stored.
compress	Compression flags (1 == compress, 0 = don't compress).

Returns:: bytes written on successful write, 0 on failure.

This function will write the specified chunk of data to the eet file and return greater than 0 on success. 0 will be returned on failure.

The eet file handle must be a valid file handle for an eet file opened for writing. If it is not, 0 will be returned and no action will be performed.

Name, and data must not be NULL, and size must be > 0. If these conditions are not met, 0 will be returned.

The data will be copied (and optionally compressed) in ram, pending a flush to disk (it will stay in ram till the eet file handle is closed though).

See also:: eet_write_cipher()

Since:: 1.0.0

3.0

Examples:: eet-basic.c, and eet-file.c.

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation