libtio concepts

The library interface follows a certain amount of concepts which makes it consistent.

Namespace

In order to interfere as little as possible with user definitions, the library uses a “namespace” which is represented by prefixes for all of its external declarations, definitions and macros. Even for code that uses libtio, avoid defining anything with any of these prefixes or you’ll get an undefined behaviour.

The reserved prefixes are tio_, TIO_, libtio_ and LIBTIO_.

Structure namespaces

For structures you can access the members, these have as prefixes the structure name in order, once again, to not interfere with user code.

For example, if a struct tio_my_type is defined, all member names will start with tio_my_type_, for example:

#include <libtio/cdefs.h>
TIO_STRUCT(tio_my_type, tio_my_type_t)

struct tio_my_type {
        int tio_my_type_a;
        char const *tio_my_type_b;
};

Objects

The library is based around objects and functions for using and managing them. The objects are defined as anonymous structures, which means you can’t access the content of these objects directly, you need to use some getters for compatibility.

Errors

Almost all functions that can fail in libtio return an int, even if they open a handle or descriptor of some kind (which is usually passed by using a pointer to it as a first argument). This integer corresponds to the error that occured in the function, or zero, representing the “everything went fine” error.

The errors that can happen in libtio are defined in <libtio/error.h>, although as usual, you should include <libtio.h> to access the code and utilities.

Some errors are “relative”, which means their significance depends on the function that returned it, when others are not. For example, tio_error_op means the function has received arguments that it doesn’t manage (sometimes, yet), and it should not be transmitted as is, while tio_error_read can be transmitted without any risk.

To get the full list of errors, you should read the header directly. If you simply want to get the error name or description, you can use the following functions:

char const *tio_error_name(int code)

Get a pointer to the error name (which you shall not free).

char const *tio_error_desc(int code)

Get a pointer to the error description (which you shall not free).

The description string should only be used for displaying the error, as it could be translated in future versions of the library.