diff --git a/doc/api/httplib_closedir.md b/doc/api/httplib_closedir.md new file mode 100644 index 00000000..8c1f266c --- /dev/null +++ b/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) diff --git a/doc/api/httplib_kill.md b/doc/api/httplib_kill.md new file mode 100644 index 00000000..7f1acdf8 --- /dev/null +++ b/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) diff --git a/doc/api/httplib_mkdir.md b/doc/api/httplib_mkdir.md new file mode 100644 index 00000000..bbed77bb --- /dev/null +++ b/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) diff --git a/doc/api/httplib_opendir.md b/doc/api/httplib_opendir.md new file mode 100644 index 00000000..f47561a3 --- /dev/null +++ b/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) diff --git a/doc/api/httplib_poll.md b/doc/api/httplib_poll.md new file mode 100644 index 00000000..f68da2e4 --- /dev/null +++ b/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) diff --git a/doc/api/httplib_readdir.md b/doc/api/httplib_readdir.md new file mode 100644 index 00000000..7961e9d3 --- /dev/null +++ b/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)