summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--luxio.c230
1 files changed, 141 insertions, 89 deletions
diff --git a/luxio.c b/luxio.c
index 0da3270..42a922a 100644
--- a/luxio.c
+++ b/luxio.c
@@ -397,12 +397,14 @@ luxio_getppid(lua_State *L) /* 4.1.1 */
return 1;
}
-/**# User identification *****************************************************/
+/*** User identification.
+@section userident
+*/
-/**% getuid
- * retval = getuid();
- * retval = getuid()
- */
+/*** Get user identity.
+@treturn number uid
+@function getuid
+*/
static int
luxio_getuid(lua_State *L) /* 4.2.1 */
{
@@ -411,10 +413,10 @@ luxio_getuid(lua_State *L) /* 4.2.1 */
return 1;
}
-/**% geteuid
- * retval = geteuid();
- * retval = geteuid()
- */
+/*** Get effective user identity.
+@treturn number uid
+@function geteuid
+*/
static int
luxio_geteuid(lua_State *L) /* 4.2.1 */
{
@@ -423,10 +425,10 @@ luxio_geteuid(lua_State *L) /* 4.2.1 */
return 1;
}
-/**% getgid
- * retval = getgid();
- * retval = getgid()
- */
+/*** Get group identity.
+@treturn number gid
+@function getgid
+*/
static int
luxio_getgid(lua_State *L) /* 4.2.1 */
{
@@ -435,10 +437,10 @@ luxio_getgid(lua_State *L) /* 4.2.1 */
return 1;
}
-/**% getegid
- * retval = getegid();
- * retval = getegid()
- */
+/*** Get effective group identity.
+@treturn number gid
+@function getegid
+*/
static int
luxio_getegid(lua_State *L) /* 4.2.1 */
{
@@ -447,10 +449,12 @@ luxio_getegid(lua_State *L) /* 4.2.1 */
return 1;
}
-/**% setuid
- * retval = setuid(uid);
- * retval, errno = setuid(uid)
- */
+/*** Set user identity.
+@tparam number uid
+@treturn number return value
+@treturn errno errno
+@function setuid
+*/
static int
luxio_setuid(lua_State *L) /* 4.2.2 */
{
@@ -462,10 +466,12 @@ luxio_setuid(lua_State *L) /* 4.2.2 */
return 2;
}
-/**% setgid
- * retval = setgid(gid);
- * retval, errno = setgid(gid)
- */
+/*** Set group identity
+@tparam number gid
+@treturn number return value
+@treturn errno errno
+@function setgid
+*/
static int
luxio_setgid(lua_State *L) /* 4.2.2 */
{
@@ -479,11 +485,11 @@ luxio_setgid(lua_State *L) /* 4.2.2 */
/* TODO: getgroups() 4.2.3 */
-/**% getlogin
- * retval = getlogin_r(buf, bufsize);
- * retval, login = getlogin()
- * retval, errno = getlogin()
- */
+/*** Get username.
+@treturn number return value
+@treturn string|errno username or errno
+@function getlogin
+*/
static int
luxio_getlogin(lua_State *L) /* 4.2.4 */
{
@@ -503,19 +509,33 @@ luxio_getlogin(lua_State *L) /* 4.2.4 */
return 2;
}
-/* 4.3 Process groups ********************************************************/
+/*** Process groups.
+@section procgroup
+*/
/* TODO: getpgrp() 4.3.1 */
/* TODO: setsid() 4.3.2 */
/* TODO: setpgid() 4.3.3 */
-/**# System identification ***************************************************/
+/*** System identification.
+@section sysident
+*/
-/**% uname
- * retval = uname(buf);
- * retval, utsname = uname() -- A table containing struct fields
- * retval, errno = uname()
- */
+/*** uname() information table.
+Returned by @{uname}. Some fields are OS-specific.
+@field sysname Operating system name, such as Linux or NetBSD.
+@field nodename System's name
+@field release Operating systems's release version
+@field machine Hardware identifier
+@field domainname NIS or YP domain name
+@table uname-table
+*/
+
+/*** Get name and information about current kernel.
+@treturn number return value
+@treturn uname-table|errno result table, or errno.
+@function uname
+*/
static int
luxio_uname(lua_State *L) /* 4.4.1 */
{
@@ -550,12 +570,15 @@ luxio_uname(lua_State *L) /* 4.4.1 */
return 2;
}
-/**# Time ********************************************************************/
+/*** Time.
+@section time
+*/
-/**% time
- * retval = time(NULL);
- * retval, errno = time()
- */
+/*** Get time in seconds.
+@treturn number seconds since epoch.
+@treturn number errno
+@function time
+*/
static int
luxio_time(lua_State *L) /* 4.5.1 */
{
@@ -565,11 +588,20 @@ luxio_time(lua_State *L) /* 4.5.1 */
return 2;
}
-/**% times
- * retval = times(buf);
- * retval, tms = times() -- A table containing utime, stime, cutime, cstime
- * retval, errno = times()
- */
+/*** times() information table.
+Returned by @{times}.
+@field utime user time
+@field stime system time
+@field cutime user time of children
+@field cstime system time of children
+@table times-table
+*/
+
+/*** Get process times.
+@treturn number return value
+@treturn times-table|errno Time data, or errno.
+@function times
+*/
static int
luxio_times(lua_State *L) /* 4.5.2 */
{
@@ -598,12 +630,15 @@ luxio_times(lua_State *L) /* 4.5.2 */
return 2;
}
-/**# Environment variables ****************************************************/
+/*** Environment variables.
+@section envvar
+*/
-/**% getenv
- * retval = getenv(name);
- * retval = getenv(name)
- */
+/*** Get an environment variable.
+@tparam string name
+@treturn string|nil return value
+@function getenv
+*/
static int
luxio_getenv(lua_State *L) /* 4.6.1 */
{
@@ -619,10 +654,14 @@ luxio_getenv(lua_State *L) /* 4.6.1 */
return 1;
}
-/**% setenv
- * retval = setenv(name, value, overwrite);
- * retval, errno = setenv(name, value[, overwrite/1])
- */
+/*** Set an environment variable.
+@tparam string name
+@tparam string value
+@tparam[opt=0] number overwrite
+@treturn number return value
+@treturn errno
+@function setenv
+*/
static int
luxio_setenv(lua_State *L) /* POSIX.1-2001 */
{
@@ -636,10 +675,12 @@ luxio_setenv(lua_State *L) /* POSIX.1-2001 */
return 2;
}
-/**% unsetenv
- * retval = unsetenv(name);
- * retval, errno = unsetenv(name)
- */
+/*** Unsets an environment variable.
+@tparam string name
+@treturn number return value
+@treturn errno
+@function unsetenv
+*/
static int
luxio_unsetenv(lua_State *L) /* POSIX.1-2001 */
{
@@ -660,12 +701,11 @@ luxio_unsetenv(lua_State *L) /* POSIX.1-2001 */
/* TODO: sysconf() 4.8.1 */
-/**# Directories *************************************************************/
-
-/**>
- * `readdir()` is a hideous API. As such, we need to be reasonably high-level
- * here, otherwise everything is just too painful.
- */
+/*** Directories.
+readdir() is a hideous API. As such, we need to be reasonably high-level here,
+otherwise everything is just too painful.
+@section dir
+*/
#define LUXIO_READDIR_METATABLE "luxio.readdir"
@@ -714,11 +754,13 @@ luxio__bless_readdir(lua_State *L)
lua_setmetatable(L, -2);
}
-/**% opendir
- * handle = opendir(path);
- * nil, errno = opendir(path)
- * handle, errno = opendir(path)
- */
+
+/*** Open a directory for enumeration.
+@tparam string dir directory to enumerate
+@treturn DIR|nil DIR object, or nil on error
+@treturn errno errno
+@function opendir
+*/
static int
luxio_opendir(lua_State *L) /* 5.1.2 */
{
@@ -749,11 +791,12 @@ luxio_opendir(lua_State *L) /* 5.1.2 */
return 1;
}
-/**% fdopendir
- * retval = fdopendir(fd);
- * nil, errno = fdopendir(fd)
- * handle, errno = fdopendir(fd)
- */
+/*** Open a directory for enumeration by open fd.
+@tparam number fd file descriptor
+@treturn DIR|nil DIR object, or nil on error
+@treturn errno errno
+@function fdopendir
+*/
static int
luxio_fdopendir(lua_State *L) /* POSIX.1-2008 */
{
@@ -784,10 +827,10 @@ luxio_fdopendir(lua_State *L) /* POSIX.1-2008 */
return 1;
}
-/**% closedir
- * closedir(handle);
- * closedir(handle)
- */
+/*** Close a previously open directory.
+@tparam DIR handle DIR object to close
+@function closedir
+*/
static int
luxio_closedir(lua_State *L) /* 5.1.2 */
{
@@ -804,11 +847,20 @@ luxio_closedir(lua_State *L) /* 5.1.2 */
return 0;
}
-/**% readdir
- * retval = readdir_r(handle, buf, ent);
- * nil, errno = readdir(handle) -- error _or_ end of directory
- * dirent, errno = readdir(handle) -- table with d_ino, d_name, and d_type
- */
+/*** readdir() information table.
+Returned by @{readdir}. Some fields are OS-specific.
+@field d_ino inode number
+@field d_name file name
+@field d_type file type
+@table dirent
+*/
+
+/*** Read a directory entry
+@tparam DIR handle directory handle
+@treturn dirent|nil directory entry table, or nil on error
+@treturn errno errno
+@function readdir
+*/
static int
luxio_readdir(lua_State *L) /* 5.1.2 */
{
@@ -843,10 +895,10 @@ luxio_readdir(lua_State *L) /* 5.1.2 */
return 1;
}
-/**% rewinddir
- * rewinddir(handle);
- * rewinddir(handle)
- */
+/*** Reset directory stream
+@tparam DIR handle
+@function rewinddir
+*/
static int
luxio_rewinddir(lua_State *L) /* 5.1.2 */
{