summaryrefslogtreecommitdiff
path: root/luxio.c
diff options
context:
space:
mode:
authorRob Kendrick (plinth) <rjek@rjek.com>2013-11-28 10:44:39 +0000
committerRob Kendrick (plinth) <rjek@rjek.com>2013-11-28 10:44:39 +0000
commit52f035eaf334b8573e0a2b81eadb704c7ae2ea14 (patch)
tree3d56ccd218a9221bc8cd30b1200790ad6bd6154f /luxio.c
parented8f7d0d066f9d9b82801ede35dfb69133080817 (diff)
downloadluxio-52f035eaf334b8573e0a2b81eadb704c7ae2ea14.tar.bz2
Start on documentation using ldoc
Diffstat (limited to 'luxio.c')
-rw-r--r--luxio.c228
1 files changed, 142 insertions, 86 deletions
diff --git a/luxio.c b/luxio.c
index 3507464..0da3270 100644
--- a/luxio.c
+++ b/luxio.c
@@ -1,4 +1,4 @@
-/**!# Light Unix I/O for Lua
+/* Light Unix I/O for Lua
* Copyright 2012 Rob Kendrick <rjek+luxio@rjek.com>
*
* Copyright 2012 Daniel Silverstone <dsilvers@digital-scurf.org>
@@ -6,6 +6,24 @@
* Distributed under the same terms as Lua itself (MIT).
*/
+/***
+Low-level bindings to POSIX functionality.
+
+Luxio provides a very light-weight binding to many of the standard POSIX
+and common Unix library calls. Where possible, calls are very raw. In
+cases such as the `dirent` family, BSD sockets, the `getaddrinfo` family,
+and some other cases, they interfaces are somewhat "cooked" either to make
+them more efficient or even possible.
+
+For the simple raw uncooked functions, all we present here is an example
+of the C prototype, and possible styles for use in Lua. You'll have to
+go looking in man pages for actual information on their use.
+
+Not all systems will provide all the functions described here.
+
+@module luxio
+*/
+
#define LUXIO_RELEASE 6 /* clients use to check for features/bug fixes */
#define LUXIO_ABI 0 /* clients use to check the ABI of calls is same */
#define LUXIO_COPYRIGHT "Copyright 2013 Rob Kendrick <rjek+luxio@rjek.com>\n" \
@@ -57,28 +75,18 @@
int luaopen_luxio(lua_State *L);
-/**# Introduction ************************************************************/
+/*** Process creation and execution.
+Functions to do with the creation of new processes and the execution of other
+programs.
+@section process
+*/
-/**>
- * Luxio provides a very light-weight binding to many of the standard POSIX
- * and common Unix library calls. Where possible, calls are very raw. In
- * cases such as the `dirent` family, BSD sockets, the `getaddrinfo` family,
- * and some other cases, they interfaces are somewhat "cooked" either to make
- * them more efficient or even possible.
- *
- * For the simple raw uncooked functions, all we present here is an example
- * of the C prototype, and possible styles for use in Lua. You'll have to
- * go looking in man pages for actual information on their use.
- *
- * Not all systems will provide all the functions described here.
- */
+/*** Create a child process.
-/**# Process creation and execution ******************************************/
-
-/**% fork
- * retval = fork();
- * retval, errno = fork()
- */
+@treturn number return value
+@treturn errno errno
+@function fork
+*/
static int
luxio_fork(lua_State *L) /* 3.1.1 */
{
@@ -122,20 +130,30 @@ luxio__exec(lua_State *L, bool usep)
return 2;
}
-/**% exec
- * retval = execv(path, argv[]);
- * retval, errno = exec(path, ...)
- */
+/*** Execute a file.
+Calls execv().
+
+@tparam string path absolute path to executable
+@tparam string ... parameters to pass to executatable
+@treturn number return value
+@treturn errno errno
+@function exec
+*/
static int
luxio_exec(lua_State *L) /* 3.1.2 */
{
return luxio__exec(L, false);
}
-/**% execp
- * retval = execvp(file, argv[]);
- * retval, errno = execp(file, ...)
- */
+/*** Execute a file, searching PATH.
+Calls execp().
+
+@tparam string path name of executable
+@tparam string ... parameters to pass to executatable
+@treturn number return value
+@treturn number errno
+@function execp
+*/
static int
luxio_execp(lua_State *L) /* 3.1.2 */
{
@@ -144,13 +162,19 @@ luxio_execp(lua_State *L) /* 3.1.2 */
/* TODO: pthread_atfork() 3.1.3 */
-/**# Process termination */
+/*** Process termination.
+Functions to do with the termination of processes.
+@section termination
+*/
-/**% waitpid
- * retval = waitpid(pid, *status, options);
- * retval, status = waitpid(pid, options)
- * retval, errno = waitpid(pid, options)
- */
+/*** Wait for a process to change state.
+
+@tparam number pid pid to wait on
+@tparam number options options for call
+@treturn number return value
+@treturn number|errno status code or errno if error
+@function waitpid
+*/
static int
luxio_waitpid(lua_State *L) /* 3.2.1 */
{
@@ -176,28 +200,36 @@ luxio_waitpid(lua_State *L) /* 3.2.1 */
return 1; \
}
-/**% WIFEXITED
- * retval = WIFEXITED(status);
- * retval = WIFEXITED(status)
- */
+/*** Check status macro for WIFEXITED.
+@tparam number status code from `waitpid`()
+@treturn number true or false
+@function WIFEXITED
+*/
WAITPID_STATUS(WIFEXITED)
/**% WEXITSTATUS
* retval = WEXITSTATUS(status);
* retval = WIFEXITED(status)
*/
+/*** Obtain exit status code from child
+@tparam number status code from `waitpid`()
+@treturn number exit status code
+@function WEXITSTATUS
+*/
WAITPID_STATUS(WEXITSTATUS)
-/**% WIFSIGNALED
- * retval = WIFSIGNALED(status);
- * retval = WIFSIGNALED(status)
- */
+/*** Check status macro for WIFSIGNALED.
+@tparam number status code from `waitpid`()
+@treturn number true or false
+@function WIFSIGNALLED
+*/
WAITPID_STATUS(WIFSIGNALED)
-/**% WTERMSIG
- * retval = WTERMSIG(status);
- * retval = WTERMSIG(status);
- */
+/*** Obtain signal used to kill child.
+@tparam number status code from `waitpid`()
+@treturn number signal number
+@function WTERMSIG
+*/
WAITPID_STATUS(WTERMSIG)
#ifdef WCOREDUMP
@@ -205,35 +237,44 @@ WAITPID_STATUS(WTERMSIG)
* retval = WCOREDUMP(status);
* retval = WCOREDUMP(status)
*/
+/*** Check status macro for WCOREDUMP.
+@tparam number status code from `waitpid`()
+@treturn number true or false
+@function WCOREDUMP
+*/
WAITPID_STATUS(WCOREDUMP)
#endif
-/**% WIFSTOPPED
- * retval = WIFSTOPPED(status);
- * retval = WIFSTOPPED(status)
- */
+/*** Check status macro for WIFSTOPPED.
+@tparam number status code from `waitpid`()
+@treturn number true or false
+@function WIFSTOPPED
+*/
WAITPID_STATUS(WIFSTOPPED)
-/**% WSTOPSIG
- * retval = WSTOPSIG(status);
- * retval = WSTOPSIG(status)
- */
+/*** Obtain signal number used to stop child.
+@tparam number status code from `waitpid`()
+@treturn number signal number
+@function WSTOPSIG
+*/
WAITPID_STATUS(WSTOPSIG)
#ifdef WIFCONTINUED
-/**% WIFCONTINUED
- * retval = WIFCONTINUED(status);
- * retval = WIFCONTINUED(status)
- */
+/*** Check status macro for WIFCONTINUED.
+Linux 2.6.10.
+@tparam number status code from `waitpid`()
+@treturn number true or false
+@function WIFCONTINUED
+*/
WAITPID_STATUS(WIFCONTINUED)
#endif
#undef WAITPID_STATUS
-/**% _exit
- * _exit(status);
- * _exit(status)
- */
+/*** Terminate calling process. Does not return.
+@tparam[opt=0] number exit status code.
+@function _exit
+*/
static int
luxio__exit(lua_State *L) /* 3.2.2 */
{
@@ -244,12 +285,21 @@ luxio__exit(lua_State *L) /* 3.2.2 */
return 0;
}
-/**# Signals *****************************************************************/
+/*** Signals. Functions related to sending signals.
+@section signals
+*/
/**% kill
* retval = kill(pid, sig);
* retval, errno = kill(pid, sig)
*/
+/*** Send signal to a process.
+@tparam number pid signal destination
+@tparam number signal signal to send
+@treturn number return value
+@treturn errno errno
+@function kill
+*/
static int
luxio_kill(lua_State *L) /* 3.3.2 */
{
@@ -273,12 +323,15 @@ luxio_kill(lua_State *L) /* 3.3.2 */
/* TODO: sigqueue() 3.3.9 */
/* TODO: pthread_kill() 3.3.10 */
-/**# Timer operations ********************************************************/
+/*** Timer operations.
+@section timer
+*/
-/**% alarm
- * retval = alarm(seconds);
- * retval = alarm(seconds)
- */
+/*** Set an alarm clock for delivery of a signal.
+@tparam number seconds How long to wait before signal delivery
+@treturn number return value
+@function alarm
+*/
static int
luxio_alarm(lua_State *L) /* 3.4.1 */
{
@@ -288,10 +341,10 @@ luxio_alarm(lua_State *L) /* 3.4.1 */
return 1;
}
-/**% pause
- * retval = pause();
- * retval, errno = pause()
- */
+/*** Wait for a signal.
+@treturn number return value
+@function pause
+*/
static int
luxio_pause(lua_State *L) /* 3.4.2 */
{
@@ -301,10 +354,11 @@ luxio_pause(lua_State *L) /* 3.4.2 */
return 2;
}
-/**% sleep
- * retval = sleep(seconds);
- * retval = sleep(seconds)
- */
+/*** Sleep for the specified number of seconds.
+@tparam number seconds number of seconds to sleep
+@treturn number return value
+@function sleep
+*/
static int
luxio_sleep(lua_State *L) /* 3.4.3 */
{
@@ -315,12 +369,14 @@ luxio_sleep(lua_State *L) /* 3.4.3 */
return 1;
}
-/**# Process identification **************************************************/
+/*** Process identification
+@section procident
+*/
-/**% getpid
- * retval = getpid();
- * retval = getpid()
- */
+/*** Get process identification.
+@treturn number pid
+@function getpid
+*/
static int
luxio_getpid(lua_State *L) /* 4.1.1 */
{
@@ -329,10 +385,10 @@ luxio_getpid(lua_State *L) /* 4.1.1 */
return 1;
}
-/**% getppid
- * retval = getppid();
- * retval = getppid()
- */
+/*** Get process's parent's identification.
+@treturn number pid
+@function getppid
+*/
static int
luxio_getppid(lua_State *L) /* 4.1.1 */
{