Notify API
----------

This API is here to provide an abstraction to the underlaying low-level filesystem notification mechanism
to try to make applications portable but also throw away detail from client-code.

IMPORTANT: The design is only tested with inotify and the API may
need to change in the future to support more subsystems that may have some limitations. 

Data structures
~~~~~~~~~~~~~~~

* `notify_event`

Holds information about one perticular event

`type`::
    The type of event, can hold one and only one of these flags

NOTIFY_UNKNOWN;;
    Events that do occur but can't be mapped to a more relevant type ends up being marked as
    an unknown event, you can most likely only tell that "something" happened on
    the given path (so unless your application wants to know that "something" happened, ignore this)

NOTIFY_CREATE;;
    A file/directory was created on the filesystem.

NOTIFY_DELETE;;
    A file/directory was deleted from the filesystem
+
IMPORTANT: It is possible to get just one event for a directory that has files/subdirectorys,
    so when getting this event you should always make sure your actions does handle the possible recursion.

NOTIFY_MOVE_FROM;;
NOTIFY_MOVE_TO;;
    As of the time of writing no implementation support these types and uses create/delete types instead.
    A drastic design change to the `notify_event` structure should be made before this type of events
    will be usefull.

`dir`::
    non zero if event is triggered on a directory
    
`path`::
    path of the triggered event
    
`filename`::
    the filename the event was triggered on

Functions
~~~~~~~~~

`notify_init()`::

    instantiate notify. making it ready for further `notify_*` calls. +
    returns a positive number if everything went OK. +
    returns zero if notify has already been instantiated. +
    And returns -1 and sets `errno` if an error occur.

`notify_add_watch()`::

    tells notify to start listening on 'path'. +
    one create event will be genereted for every file under 'path' +
    and all subdirectorys will be watched. +
    returns 1 if everything went ok and returns -1 and sets `errno` if an error occure.

`notify_rm_watch()`::

    'path' will be removed from notify and all events triggered on this path
    will be ignored from now on.

`notify_read()`::

    fetches and returns one event from the subsystem. A `NULL` pointer is returned if no events
    is available at the given moment.
+
NOTE: The implementation may read and process the data from whatever source it has
in this function, the only requirement is that the function never blocks.

`notify_exit()`::

    free's all memory associated with notify and other cleanup routines.

`notify_event_new()`::

    allocates memory and initilize values for a new `notify_event` structure

`notify_event_clear()`::

    free's all the memory and sets values back to default.

`notify_event_set_*()`::

    use these functions to set members of the `notify_event` structure.
    
`notify_event_del()`::

    free's all the memory from the `notify_event` structure.

`notify_event_typetostr()`::

    returns a string representation of a event's type. the pointer should +
    not be free'ed, so its safe to be used like this:
+
==========================
printf("type: %s\n", notify_event_typetostr(event));
==========================
