Added utility function docs

doc/api/httplib_closedir.md

@@ -0,0 +1,27 @@
+# LibHTTP API Reference
+
+### `httplib_closedir( dir );`
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+|**`dir`**|`DIR *`| A pointer to a directory structure of an opened directory |
+
+### Return Value
+
+| Type | Description |
+| :--- | :--- |
+|`int`|Success or error code of the operation|
+
+### Description
+
+The function `httplib_closedir()` is a platform independent way to close a directory which was previously opened with a call to [`httplib_opendir()`](httplib_opendir.md). The function returns an integer which indicates the result of the operation. The return value **0** is returned if closing the directory succesful. The file associated with the directory has been closed in that situation and previously allocated memory by the `httplib_opendir()` function is returned to the heap. The directory structure to which the parameter `dir` points will in that case be invalid and should not be further used by the calling party. An error is signaled by returning the value **-1**.
+
+On functions which support Posix the `httplib_closedir()` is a direct wrapper around `opendir()`. On other systems the functionality of the Posix function is emulated with own code.
+
+### See Also
+
+* [`httplib_mkdir();`](httplib_mkdir.md)
+* [`httplib_opendir();`](httplib_opendir.md)
+* [`httplib_readdir();`](httplib_readdir.md)

doc/api/httplib_kill.md

@@ -0,0 +1,26 @@
+# LibHTTP API Reference
+
+### `httplib_kill( pid, sig );`
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+|**`pid`**|`pid_t`| The process identifier of the process |
+|**`sig`**|`int`| The signal to be sent to the process |
+
+### Return Value
+
+| Type | Description |
+| :--- | :--- |
+|`int`|An integer which indicates success or failure|
+
+### Description
+
+The function `httplib_kill()` provides a platform independent way to send a signal to a process. The function uses the Postfix `kill()` functions in environments where that function is supported or emulates that function with own code for other operating systems. The function call returns **0** if sending the signal was successful and **-1** otherwise.
+
+Please note that for non Posix-compliant systems the functionality of the Posix `kill()` function has not been fully implemented. Currently only the `SIGKILL` has been implemented and tested fully. For other signals the functionality is unknown and may not lead to the desired results.
+
+### See Also
+
+* [`httplib_poll();`](httplib_poll.md)

doc/api/httplib_mkdir.md

@@ -0,0 +1,28 @@
+# LibHTTP API Reference
+
+### `httplib_mkdir( path, mode );`
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+|**`path`**|`const char *`| A pointer to name of the directory to create |
+|**`mode`**|`const char *`| The security attributes to be assigned to the directory |
+
+### Return Value
+
+| Type | Description |
+| :--- | :--- |
+|`int`|An integer which indicates success or failure of the call|
+
+### Description
+
+The function `httplib_mkdir()` provides an independent way to creare a directory on a system. The function uses the Posix `mkdir()` function in environments where that function is supported or emulates that function with own code for other operating systems. Please note that the `mode` parameter resembles the \*nix security attributes known for files and directories. On systems which do not support that—most notably Windows based systems—the `mode` parameter is silently ignored.
+
+The `httplib_mkdir()` function returns **0** when it was successful and **-1** when an error occured.
+
+### See Also
+
+* [`httplib_closedir();`](httplib_closedir.md)
+* [`httplib_opendir();`](httplib_opendir.md)
+* [`httplib_readdir();`](httplib_readdir.md)

doc/api/httplib_opendir.md

@@ -0,0 +1,29 @@
+# LibHTTP API Reference
+
+### `httplib_opendir( name );`
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+|**`name`**|`const char *`| A pointer to name of the directory to open |
+
+### Return Value
+
+| Type | Description |
+| :--- | :--- |
+|`DIR *`|A pointer to a directory structure or NULL on error|
+
+### Description
+
+The function `httplib_opendir()` provides a platform independent way to open a directory on a system. The function uses the Posix `opendir()` function in environments where that function is supported or emulates that function with own code for other operating systems. The function is either a pointer to a DIR directory structure if the call was succesful, or a `NULL` pointer if the directory cannot be found or an other error occured.
+
+Reading individual items in the directory is possible with the `httplib_readdir()`  function.
+
+Please note that the `httplib_opendir()` function allocates memory and opens the directory as a file on most platforms. Closing the directory and returning the allocated resources after use of the directory is finished is therefore necessary. Closing a directory can be done with a call to the [`httplib_closedir()`](httplib_closedir.md) function.
+
+### See Also
+
+* [`httplib_closedir();`](httplib_closedir.md)
+* [`httplib_mkdir();`](httplib_mkdir.md)
+* [`httplib_readdir();`](httplib_readdir.md)

doc/api/httplib_poll.md

@@ -0,0 +1,27 @@
+# LibHTTP API Reference
+
+### `httplib_poll( pfd, n, timeout );`
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+|**`pfd`**|`struct pollfd *`|List of file descriptors|
+|**`nfds`**|`unsigned int`|Number of file descriptors|
+|**`timeout`**|`int`|Timeout of the wait in milliseconds|
+
+### Return Value
+
+| Type | Description |
+| :--- | :--- |
+|`int`|The number of descriptors ready for I/O or an error code|
+
+### Description
+
+The function `httplib_poll()` provides a platform independent way to perform asynchronous I/O. A list with file descriptors is provided as parameter to the function call. When one or more file desciptors are ready to provide I/O the function returns with the number of descriptors which are ready. An error is indicated with the value -1. An optional timeout value specifies in milliseconds after which time the function should return, even if no file descriptors are ready. The value **-1** as timeout is interpreted as an infinite wait.
+
+On Posix compliant systems the call to this function is just a wrapper around the Posix `poll()` function. On other systems this function is implemented with own code to emulate the Posix functionality.
+
+### See Also
+
+* [`httplib_kill();`](httplib_kill.md)

doc/api/httplib_readdir.md

@@ -0,0 +1,29 @@
+# LibHTTP API Reference
+
+### `httplib_readdir( dir );`
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+|**`name`**|`DIR *`| A pointer to name of the directory to open |
+
+### Return Value
+
+| Type | Description |
+| :--- | :--- |
+|`struct dirent *`|A pointer to a directory entry structure or NULL on error|
+
+### Description
+
+The function `httplib_readdir()` reads the next entry from a directory. The directory must have been opened earlier with a call to the function [`httplib_opendir()`](httplib_opendir.md). If the next directory entry can be found, a pointer to a `dirent` structure is returned. If an error occurs or the last item in a directory has been read the value `NULL` is returned instead.
+
+On platforms which support Posix the call to `httplib_readdir()` is a wrapper arround `readdir()`. On other systems the function is implemented with own code as a clone of the `readdir()` function.
+
+After the last item has been read with `httplib_opendir()`, the directory must be closed with a call to [`httplib_closedir()`](httplib_closedir.md) to return occupied resources.
+
+### See Also
+
+* [`httplib_closedir();`](httplib_closedir.md)
+* [`httplib_mkdir();`](httplib_mkdir.md)
+* [`httplib_opendir();`](httplib_opendir.md)