docs: added Asciidoc support
This commit is contained in:
Henrik Hautakoski
parent
ff89dd2ded
commit
44be15984f
5 changed files with 155 additions and 130 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -3,3 +3,4 @@ Makefile.local.mk
|
|||
build/
|
||||
test/test_*
|
||||
nbproject
|
||||
docs/*.html
|
||||
|
|
|
|||
18
docs/Makefile
Normal file
18
docs/Makefile
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
|
||||
ASCIIDOC = asciidoc
|
||||
|
||||
HTML_DOCS = api-notify.html strbuf.html xalloc.html
|
||||
|
||||
ifndef VERBOSE
|
||||
QUIET_ASCIIDOC = @echo ' ' GEN $@;
|
||||
endif
|
||||
|
||||
.PHONY : clean
|
||||
all : $(HTML_DOCS)
|
||||
html : $(HTML_DOCS)
|
||||
|
||||
%.html : %.txt
|
||||
$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -o $@ $<
|
||||
|
||||
clean :
|
||||
$(RM) $(HTML_DOCS)
|
||||
|
|
@ -1,102 +1,106 @@
|
|||
-----------------------------------
|
||||
Notify API
|
||||
-----------------------------------
|
||||
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.
|
||||
|
||||
Note that the design is only tested with inotify and may
|
||||
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
|
||||
Data structures
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
notify_event:
|
||||
* `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
|
||||
|
||||
members:
|
||||
|
||||
type - the type of event (NOTIFY_* constants)
|
||||
dir - non zero if event is triggered on a directory
|
||||
path - path of the triggered event
|
||||
filename - the filename event was triggered on
|
||||
|
||||
types:
|
||||
|
||||
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, note that 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.
|
||||
|
||||
-- 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.
|
||||
`path`::
|
||||
path of the triggered event
|
||||
|
||||
returns 1 if everything went ok and returns -1 and sets 'errno' if an error occure.
|
||||
`filename`::
|
||||
the filename the event was triggered on
|
||||
|
||||
notify_rm_watch():
|
||||
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():
|
||||
`notify_read()`::
|
||||
|
||||
fetches and returns one event from the subsystem. A NULL pointer is returned if no events
|
||||
fetches and returns one event from the subsystem. A `NULL` pointer is returned if no events
|
||||
is available at the given moment.
|
||||
|
||||
Note that 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.
|
||||
+
|
||||
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():
|
||||
`notify_exit()`::
|
||||
|
||||
free's all memory associated with notify and other cleanup routines.
|
||||
|
||||
notify_event_new():
|
||||
`notify_event_new()`::
|
||||
|
||||
allocates memory and initilize values for a new 'notify_event' structure
|
||||
allocates memory and initilize values for a new `notify_event` structure
|
||||
|
||||
notify_event_clear():
|
||||
`notify_event_clear()`::
|
||||
|
||||
free's all the memory and sets values back to default.
|
||||
|
||||
notify_event_set_*():
|
||||
`notify_event_set_*()`::
|
||||
|
||||
use these functions to set members of the 'notify_event' structure.
|
||||
use these functions to set members of the `notify_event` structure.
|
||||
|
||||
notify_event_del():
|
||||
`notify_event_del()`::
|
||||
|
||||
free's all the memory from the notify_event structure.
|
||||
free's all the memory from the `notify_event` structure.
|
||||
|
||||
notify_event_typetostr():
|
||||
`notify_event_typetostr()`::
|
||||
|
||||
returns a string representation of a event's type. the pointer should
|
||||
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));
|
||||
+
|
||||
==========================
|
||||
printf("type: %s\n", notify_event_typetostr(event));
|
||||
==========================
|
||||
|
|
|
|||
|
|
@ -1,70 +1,72 @@
|
|||
---------------------
|
||||
String buffer API
|
||||
---------------------
|
||||
String buffer API
|
||||
-----------------
|
||||
|
||||
First off, the major design choices. the most important thing to keep in mind
|
||||
when using the API is that it is designed for low-level usage, The basic error checking
|
||||
is removed (like checking if the input strbuf pointer is null). This is not done to
|
||||
gain speed, but because this is a buffer API, you should in almost every case allocate
|
||||
the structure on the stack or have it passed from a function that has it allocated on the stack.
|
||||
is removed (like checking if the input strbuf pointer is null). +
|
||||
This is not done to gain speed, but because this is a buffer API, you should in almost every case allocate
|
||||
the structure on the stack or have it passed from a function that has it allocated on the stack. +
|
||||
Other types of skipped error checking is for example if the ->len member is in range of
|
||||
the allocated block. (obviously this is checked in functions that may need to expand the memory)
|
||||
|
||||
-- Data structures
|
||||
Data structures
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
strbuf_t:
|
||||
* `strbuf_t`
|
||||
|
||||
The ->buf member is yours to mess with if you want, but you should never go beyond ->len.
|
||||
A NULL terminating character is located at ->len+1 at all times so it is safe to use the ->buf member
|
||||
The ->buf member is yours to mess with if you want, but you should never go beyond ->len. +
|
||||
A `NULL` terminating character is located at ->len+1 at all times so it is safe to use the ->buf member
|
||||
on any function that relies on the input being a valid C string. The API will never rely on this
|
||||
and it's possible to have embedded null's because of that.
|
||||
and it's possible to have embedded `NULL`'s because of that.
|
||||
|
||||
->alloc_size and ->len should not be messed with, only strbuf_* functions will know how to handle those properly.
|
||||
NOTE: ->alloc_size and ->len should *not* be messed with, only `strbuf_*` functions will know how to handle those properly.
|
||||
|
||||
-- Functions
|
||||
Functions
|
||||
~~~~~~~~~
|
||||
|
||||
strbuf_append():
|
||||
`strbuf_append()`::
|
||||
|
||||
Like strncat() this function will append the buffer with the contents of 'str'
|
||||
and will always copy exactly 'len' bytes. (if memory can be obtained ofcourse)
|
||||
This function will append the buffer with the contents of 'ptr'
|
||||
and will always copy exactly 'len' bytes. (if memory can be obtained ofcourse)
|
||||
|
||||
strbuf_append_str():
|
||||
`strbuf_append_str()`::
|
||||
|
||||
Will add the C-string to the end of ->buf
|
||||
Will add the 'str' C-string to the end of ->buf
|
||||
|
||||
strbuf_append_ch():
|
||||
`strbuf_append_ch()`::
|
||||
|
||||
Adds one character 'ch' to the end of ->buf
|
||||
Adds one character 'ch' to the end of ->buf
|
||||
|
||||
strbuf_reduce():
|
||||
`strbuf_reduce()`::
|
||||
|
||||
Will reduce ->buf by 'len' bytes from the end, Note that this don't shrink the memory block
|
||||
just changes the size and properly NULL terminates the now reduced space.
|
||||
Will reduce ->buf by 'len' bytes from the end.
|
||||
+
|
||||
NOTE: This doesn't shrink the memory block
|
||||
just changes the size and properly `NULL` terminates the now reduced space.
|
||||
|
||||
strbuf_trim():
|
||||
strbuf_rtrim():
|
||||
strbuf_ltrim():
|
||||
`strbuf_trim()`::
|
||||
`strbuf_rtrim()`::
|
||||
`strbuf_ltrim()`::
|
||||
|
||||
Removes space characters from the beginning (ltrim) of the ->buf string, the end (rtrim) or both (trim).
|
||||
Removes space characters from the beginning (ltrim) of the ->buf string, the end (rtrim) or both (trim).
|
||||
|
||||
strbuf_rev():
|
||||
`strbuf_rev()`::
|
||||
|
||||
Reverses the ->buf string.
|
||||
Reverses the ->buf string.
|
||||
|
||||
strbuf_squeeze():
|
||||
`strbuf_squeeze()`::
|
||||
|
||||
Squeezes "together" sequences of 'ch' into one character.
|
||||
Squeezes "together" sequences of 'ch' into one character.
|
||||
|
||||
strbuf_term():
|
||||
`strbuf_term()`::
|
||||
|
||||
ensure the string is terminated with 'ch'. will not change the string if it is already terminated.
|
||||
ensure that ->buf is terminated with 'ch'. Will not change ->buf if it is already terminated.
|
||||
|
||||
strbuf_release():
|
||||
`strbuf_release()`::
|
||||
|
||||
This function should be used to detach the ->buf member from the strbuf_t structure.
|
||||
A malloc():ed C string of size strlen()+1 is returned that you are now responsible for.
|
||||
This function should be used to detach the ->buf member from the `strbuf_t` structure. +
|
||||
A `malloc()`'ed C string of size `strlen()+1` is returned that you are now responsible for.
|
||||
|
||||
strbuf_free():
|
||||
|
||||
Free's all the memory (allocated on the heap) associted with the strbuf_t structure.
|
||||
`strbuf_free()`::
|
||||
|
||||
Free's all the memory (allocated on the heap) associted with the `strbuf_t` structure.
|
||||
|
|
|
|||
|
|
@ -1,37 +1,37 @@
|
|||
-----------------------------------
|
||||
xalloc - safe memory allocation
|
||||
-----------------------------------
|
||||
xalloc - safe memory allocation
|
||||
-------------------------------
|
||||
|
||||
this module implements malloc and friends + some extensions.
|
||||
if __DEBUG__ symbol is defined. the functions will provide extended
|
||||
If `__DEBUG__` symbol is defined. The functions will provide extended
|
||||
debug logic and kills the program (passing 0 as size to malloc for example).
|
||||
|
||||
the funtions will at all times kill the program if memory can't be allocated for
|
||||
some reason, this makes the need for client-code to check for null pointers returned
|
||||
The funtions will at all times kill the program if memory can't be allocated for
|
||||
some reason, this makes the need for client-code to check for `NULL` pointers returned
|
||||
by these functions redundant.
|
||||
|
||||
-- functions
|
||||
functions
|
||||
~~~~~~~~~
|
||||
|
||||
xmalloc():
|
||||
`xmalloc()`::
|
||||
|
||||
just like malloc, this function allocates a block of memory of 'size' bytes.
|
||||
if compiled with the __DEBUG__ symbol, the function will not allow zero size
|
||||
Just like malloc, this function allocates a block of memory of 'size' bytes. +
|
||||
If compiled with the `__DEBUG__` symbol, the function will not allow zero size
|
||||
|
||||
xmallocz():
|
||||
`xmallocz()`::
|
||||
|
||||
exactly like xmalloc but will initialize the block with zero's.
|
||||
Exactly like xmalloc but will initialize the block with zero's.
|
||||
|
||||
xrealloc():
|
||||
`xrealloc()`::
|
||||
|
||||
reallocates a previous allocated block of memory to 'size' bytes.
|
||||
if compiled with the __DEBUG__ symbol, the function will not allow zero size
|
||||
Reallocates a previous allocated block of memory to 'size' bytes. +
|
||||
If compiled with the `__DEBUG__` symbol, the function will not allow zero size
|
||||
|
||||
xstrdup():
|
||||
`xstrdup()`::
|
||||
|
||||
allocates and copies the string 's' to a new memory location and returns it to the user.
|
||||
if compiled with the __DEBUG__ symbol, the function will not allow 's' to be a NULL pointer
|
||||
Allocates and copies the string 's' to a new memory location and returns it to the user. +
|
||||
If compiled with the `__DEBUG__` symbol, the function will not allow 's' to be a `NULL` pointer
|
||||
|
||||
xfree():
|
||||
`xfree()`::
|
||||
|
||||
free's a previous allocated block (pointed to by 'ptr') that is allocated by xmalloc/malloc.
|
||||
if compiled with the __DEBUG__ symbol, the function will not allow 'ptr' to be a NULL pointer
|
||||
Free's a previous allocated block (pointed to by 'ptr') that is allocated by xmalloc/malloc. +
|
||||
If compiled with the `__DEBUG__` symbol, the function will not allow 'ptr' to be a NULL pointer
|
||||
|
|
|
|||
Reference in a new issue