More documentation

1 files changed, 225 insertions, 17 deletions

diff --git a/luxio.c b/luxio.c
index af7b7f6..8fa5f3d 100644
--- a/luxio.c
+++ b/luxio.c
@@ -63,6 +63,10 @@ int luaopen_luxio(lua_State *L);
  * 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.
  */
 
@@ -649,10 +653,10 @@ luxio__bless_readdir(lua_State *L)
 
 	lua_setmetatable(L, -2);
 }
-/**> opendir
- * #### Lua usage
- *  - handle = opendir(path)
- *  - nil, errno = opendir(path)
+/**% opendir
+ * handle = opendir(path);
+ * nil, errno = opendir(path)
+ * handle, errno = opendir(path)
  */ 
 static int
 luxio_opendir(lua_State *L) /* 5.1.2 */
@@ -684,6 +688,11 @@ luxio_opendir(lua_State *L) /* 5.1.2 */
 	return 1;
 }
 
+/**% fdopendir
+ * retval = fdopendir(fd);
+ * nil, errno = fdopendir(fd)
+ * handle, errno = fdopendir(fd)
+ */
 static int
 luxio_fdopendir(lua_State *L) /* POSIX.1-2008 */
 {
@@ -714,6 +723,10 @@ luxio_fdopendir(lua_State *L) /* POSIX.1-2008 */
 	return 1;
 }
 
+/**% closedir
+ * closedir(handle);
+ * closedir(handle)
+ */
 static int
 luxio_closedir(lua_State *L) /* 5.1.2 */
 {
@@ -730,6 +743,11 @@ 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
+ */
 static int
 luxio_readdir(lua_State *L) /* 5.1.2 */
 {
@@ -764,6 +782,10 @@ luxio_readdir(lua_State *L) /* 5.1.2 */
 	return 1;
 }
 
+/**% rewinddir
+ * rewinddir(handle);
+ * rewinddir(handle)
+ */
 static int
 luxio_rewinddir(lua_State *L) /* 5.1.2 */
 {
@@ -774,8 +796,12 @@ luxio_rewinddir(lua_State *L) /* 5.1.2 */
 	return 0;
 }
 
-/* 5.2 Working directory *****************************************************/
+/**# Working directory *******************************************************/
 
+/**% chdir
+ * retval = chdir(path);
+ * retval, errno = chdir(path)
+ */
 static int
 luxio_chdir(lua_State *L) /* 5.2.1 */
 {
@@ -787,6 +813,11 @@ luxio_chdir(lua_State *L) /* 5.2.1 */
 	return 2;
 }
 
+/**% getcwd
+ * retval = getcwd(buf, buflen);
+ * path, errno = getcwd()
+ * nil, errno = getcwd()
+ */
 static int
 luxio_getcwd(lua_State *L) /* 5.2.2 */
 {
@@ -803,8 +834,12 @@ luxio_getcwd(lua_State *L) /* 5.2.2 */
 	return 2;
 }
 
-/* 5.3 General file creation *************************************************/
+/**# General file creation ***************************************************/
 
+/**% open
+ * fd = open(path, flags[, mode]);
+ * fd, errno = open(path, flags[, mode])
+ */
 static int
 luxio_open(lua_State *L) /* 5.3.1 */
 {
@@ -831,6 +866,10 @@ luxio_open(lua_State *L) /* 5.3.1 */
 
 /* TODO: creat() 5.3.2 */
 
+/**% umask
+ * retval = umask(mask);
+ * retval = umask(mask)
+ */
 static int
 luxio_umask(lua_State *L) /* 5.3.3 */
 {
@@ -841,6 +880,10 @@ luxio_umask(lua_State *L) /* 5.3.3 */
 	return 1;
 }
 
+/**% link
+ * retval = link(existing, new);
+ * retval, errno = link(existing, new)
+ */
 static int
 luxio_link(lua_State *L) /* 5.3.4 */
 {
@@ -853,8 +896,12 @@ luxio_link(lua_State *L) /* 5.3.4 */
 	return 2;
 }
 
-/* 5.4 Special file creation *************************************************/
+/**# Special file creation ***************************************************/
 
+/**% mkdir
+ * retval = mkdir(pathname, mode);
+ * retval, errno = mkdir(pathname, mode)
+ */
 static int
 luxio_mkdir(lua_State *L) /* 5.4.1 */
 {
@@ -867,6 +914,10 @@ luxio_mkdir(lua_State *L) /* 5.4.1 */
 	return 2;
 }
 
+/**% mkfifo
+ * retval = mkfifo(pathname, mode);
+ * retval, errno = mkfifo(pathname, mode)
+ */
 static int
 luxio_mkfifo(lua_State *L) /* 5.4.2 */
 {
@@ -879,8 +930,12 @@ luxio_mkfifo(lua_State *L) /* 5.4.2 */
 	return 2;
 }
 
-/* 5.5 File removal **********************************************************/
+/**# File removal ************************************************************/
 
+/**% unlink
+ * retval = unlink(pathname);
+ * retval, errno = unlink(pathname)
+ */
 static int
 luxio_unlink(lua_State *L) /* 5.5.1 */
 {
@@ -892,6 +947,10 @@ luxio_unlink(lua_State *L) /* 5.5.1 */
 	return 2;
 }
 
+/**% rmdir
+ * retval = rmdir(pathname);
+ * retval, errno = rmdir(pathname)
+ */
 static int
 luxio_rmdir(lua_State *L) /* 5.5.2 */
 {
@@ -903,6 +962,10 @@ luxio_rmdir(lua_State *L) /* 5.5.2 */
 	return 2;
 }
 
+/**% rename
+ * retval = rename(old, new);
+ * retval, errno = rename(old, new)
+ */
 static int
 luxio_rename(lua_State *L) /* 5.5.3 */
 {
@@ -915,7 +978,7 @@ luxio_rename(lua_State *L) /* 5.5.3 */
 	return 2;
 }
 
-/* 5.6 File characteristics **************************************************/
+/**# File characteristics ****************************************************/
 
 static void
 luxio_push_stat_table(lua_State *L, struct stat *s)
@@ -943,6 +1006,10 @@ luxio_push_stat_table(lua_State *L, struct stat *s)
 #undef PUSH_ENTRY
 }
 
+/**% stat
+ * retval = stat(pathname, statbuf);
+ * retval, errno = stat(pathname) -- 'errno' can be  table containing dev, ino, uid, gid, etc
+ */
 static int
 luxio_stat(lua_State *L) /* 5.6.2 */
 {
@@ -961,6 +1028,10 @@ luxio_stat(lua_State *L) /* 5.6.2 */
 	return 2;
 }
 
+/**% fstat
+ * retval = fstat(fd, statbuf);
+ * retval, errno = fstat(fd) -- 'errno' can be a table containing dev, ino, uid, gid, etc
+ */
 static int
 luxio_fstat(lua_State *L) /* 5.6.2 */
 {
@@ -979,6 +1050,10 @@ luxio_fstat(lua_State *L) /* 5.6.2 */
 	return 2;
 }
 
+/**% lstat
+ * retval = lstat(pathname, statbuf);
+ * retval, errno = lstat(pathname) -- 'errno' can be a table containing dev, ino, uid, gid, etc
+ */
 static int
 luxio_lstat(lua_State *L) /* POSIX.1-2001 */
 {
@@ -1003,15 +1078,49 @@ luxio_lstat(lua_State *L) /* POSIX.1-2001 */
 	return 1;                                         \
 	}
 
+/**% S_ISREG
+ * retval = S_ISREG(m);
+ * retval = S_ISREG(m)
+ */
 STAT_IS(REG)
+
+/**% S_ISDIR
+ * retval = S_ISDIR(m);
+ * retval = S_ISDIR(m)
+ */
 STAT_IS(DIR)
+
+/**% S_ISCHR
+ * retval = S_ISCHR(m);
+ * retval = S_ISCHR(m)
+ */
 STAT_IS(CHR)
+
+/**% S_ISBLK
+ * retval = S_ISBLK(m);
+ * retval = S_ISBLK(m)
+ */
 STAT_IS(BLK)
+
+/**% S_ISFIFO
+ * retval = S_ISFIFO(m);
+ * retval = S_ISFIFO(m)
+ */
 STAT_IS(FIFO)
+
 #ifdef S_ISLNK
+/**% S_ISLNK
+ * retval = S_ISLNK(m);
+ * retval = S_ISLNK(m)
+ */
 STAT_IS(LNK)
 #endif
+
 #ifdef S_ISSOCK
+/**% S_ISSOCK
+ * retval = S_ISSOCK(m);
+ * retval = S_ISSOCK(m)
+ */
 STAT_IS(SOCK)
 #endif
 
@@ -1019,6 +1128,10 @@ STAT_IS(SOCK)
 
 /* TODO: access() 5.6.3 */
 
+/**% chmod
+ * retval = chmod(path, mode);
+ * retval, errno = chmod(path, mode)
+ */
 static int
 luxio_chmod(lua_State *L) /* 5.6.4 */
 {
@@ -1031,6 +1144,10 @@ luxio_chmod(lua_State *L) /* 5.6.4 */
 	return 2;
 }
 
+/**% fchmod
+ * retval = fchmod(fd, mode);
+ * retval, errno = fchmod(fd, mode)
+ */
 static int
 luxio_fchmod(lua_State *L) /* 5.6.4 */
 {
@@ -1043,6 +1160,10 @@ luxio_fchmod(lua_State *L) /* 5.6.4 */
 	return 2;
 }
 
+/**% chown
+ * retval = chown(path, owner, group);
+ * retval, errno = chown(path, owner, group)
+ */
 static int
 luxio_chown(lua_State *L) /* 5.6.5 */
 {
@@ -1058,6 +1179,10 @@ luxio_chown(lua_State *L) /* 5.6.5 */
 
 /* TODO: utime() 5.6.6 */
 
+/**% ftruncate
+ * retval = ftruncate(fd, length);
+ * retval, errno = ftruncate(fd, length)
+ */
 static int
 luxio_ftruncate(lua_State *L) /* 5.6.7 */
 {
@@ -1074,8 +1199,12 @@ luxio_ftruncate(lua_State *L) /* 5.6.7 */
 
 /* TODO: pathconf(), fpathconf() 5.7.1 */
 
-/* 6.1 Pipes *****************************************************************/
+/**# Pipes *******************************************************************/
 
+/**% pipe
+ * retval = pipe(pipearray);
+ * retval, errno = pipe(pipetable) -- fills in [1] and [2] in pipetable
+ */
 static int
 luxio_pipe(lua_State *L) /* 6.1.1 */
 {
@@ -1097,6 +1226,11 @@ luxio_pipe(lua_State *L) /* 6.1.1 */
 }
 
 #ifdef _GNU_SOURCE
+
+/**% pipe2
+ * retval = pipe2(pipearray, flags);
+ * retval, errno = pipe2(pipetable, flags) -- fills in [1] and [2] in pipetable
+ */
 static int
 luxio_pipe2(lua_State *L) /* GNU extension */
 {
@@ -1121,6 +1255,10 @@ luxio_pipe2(lua_State *L) /* GNU extension */
 }
 #endif
 
+/**% socketpair
+ * retval = socketpair(domain, type, protocol, fdarray)
+ * retval, errno = socketpair(domain, type, protocol, fdtable)
+ */
 static int
 luxio_socketpair(lua_State *L) /* POSIX.1-2001 */
 {
@@ -1145,8 +1283,12 @@ luxio_socketpair(lua_State *L) /* POSIX.1-2001 */
 	return 2;	
 }
 
-/* 6.2 File descriptor manipulation ******************************************/
+/**# File descriptor manipulation ********************************************/
 
+/**% dup
+ * retval = dup(oldfd);
+ * retval, errno = dup(oldfd)
+ */
 static int
 luxio_dup(lua_State *L) /* 6.2.1 */
 {
@@ -1158,6 +1300,10 @@ luxio_dup(lua_State *L) /* 6.2.1 */
 	return 2;
 }
 
+/**% dup2
+ * retval = dup2(oldfd, newfd);
+ * retval, errno = dup2(oldfd, newfd)
+ */
 static int
 luxio_dup2(lua_State *L) /* 6.2.1 */
 {
@@ -1171,6 +1317,10 @@ luxio_dup2(lua_State *L) /* 6.2.1 */
 }
 
 #ifdef _GNU_SOURCE
+/**% dup3
+ * retval = dup3(oldfd, newfd, flags);
+ * retval, errno = dup2(oldfd, newfd, flags)
+ */
 static int
 luxio_dup3(lua_State *L) /* GNU extension */
 {
@@ -1185,8 +1335,12 @@ luxio_dup3(lua_State *L) /* GNU extension */
 }
 #endif
 
-/* 6.3 File descriptor deassignment ******************************************/
+/**# File descriptor deassignment ********************************************/
 
+/**% close
+ * retval = close(fd);
+ * retval, errno = close(fd)
+ */
 static int
 luxio_close(lua_State *L) /* 6.3.1 */
 {
@@ -1196,8 +1350,13 @@ luxio_close(lua_State *L) /* 6.3.1 */
 	return 2;
 }
 
-/* 6.4 Input and output ******************************************************/
+/**# Input and output ********************************************************/
 
+/**% read
+ * retval = read(fd, buf, count);
+ * retval, errno = read(fd, count)
+ * string, errno = read(fd, count)
+ */
 static int
 luxio_read(lua_State *L) /* 6.4.1 */
 {
@@ -1234,6 +1393,10 @@ luxio_read(lua_State *L) /* 6.4.1 */
     return 2;
 }
 
+/**% write
+ * retval = write(fd, buf, count);
+ * retval, errno = write(fd, string[, start_offset/0])
+ */
 static int
 luxio_write(lua_State *L) /* 6.4.2 */
 {
@@ -1250,6 +1413,10 @@ luxio_write(lua_State *L) /* 6.4.2 */
 	return 2;
 }
 
+/**% writev
+ * retval = writev(fd, iov, blks);
+ * retval, errno = writev(fd, string[, ...])
+ */
 static int
 luxio_writev(lua_State *L) /* POSIX.1-2001 */
 {
@@ -1277,6 +1444,10 @@ luxio_writev(lua_State *L) /* POSIX.1-2001 */
 }
 
 #ifdef HAVE_SENDFILE
+/**% sendfile
+ * retval = sendfile(out_fd, in_fd, offset/NULL, count);
+ * retval, errno = sendfile(out_fd, in_fd, offset/nil, count)
+ */
 static int
 luxio_sendfile(lua_State *L) /* Linux-specific */
 {
@@ -1304,6 +1475,10 @@ luxio_sendfile(lua_State *L) /* Linux-specific */
 #endif /* HAVE_SENDFILE */
 
 #ifdef HAVE_SPLICE
+/**% splice
+ * retval = splice(fd_in, off_in, fd_out, off_out, len, flags);
+ * retval, errno = splice(fd_in, off_in, fd_out, off_out, len, flags)
+ */
 static int
 luxio_splice(lua_State *L) /* Linux-specific */
 {
@@ -1328,8 +1503,17 @@ luxio_splice(lua_State *L) /* Linux-specific */
 }
 #endif
 
-/* 6.5 Control operations on files *******************************************/
+/**# Control operations on files *********************************************/
 
+/**> fcntl
+ * Supported commands:
+ *  F_GETFD/F_SETFD, F_GETFL/F_SETFL, F_GETPIPE_SZ/F_SETPIPE_SZ, F_DUPFD,
+ *  F_DUPFD_CLOEXEC.
+ *
+ * C-Style: retval = fcntl(fd, cmd[, argument]);
+ *
+ * Lua-Style: retval, errno = fcntl(fd, cmd[, argument])
+ */
 static int
 luxio_fcntl(lua_State *L) /* 6.5.2 */
 {
@@ -1386,6 +1570,10 @@ luxio_lseek(lua_State *L) /* 6.5.3 */
 	return 2;
 }
 #else
+/**% lseek
+ * retval = lseek(fd, offset, whence);
+ * retval, errno = lseek(fd, offset, whence)
+ */
 static int
 luxio_lseek(lua_State *L) /* 6.5.3 */
 {
@@ -1400,8 +1588,12 @@ luxio_lseek(lua_State *L) /* 6.5.3 */
 }
 #endif
 
-/* 6.6 File synchronisation */
+/**# File synchronisation ****************************************************/
 
+/**% fsync
+ * retval = fsync(filedes);
+ * retval, errno = fsync(filedes)
+ */
 static int
 luxio_fsync(lua_State *L) /* 6.6.1 */
 {
@@ -1413,6 +1605,10 @@ luxio_fsync(lua_State *L) /* 6.6.1 */
 	return 2;
 }
 
+/**% fdatasync
+ * retval = fdatasync(filedes);
+ * retval = fdatasync(filedes)
+ */
 static int
 luxio_fdatasync(lua_State *L) /* 6.6.2 */
 {
@@ -1435,12 +1631,16 @@ luxio_fdatasync(lua_State *L) /* 6.6.2 */
 /* TODO: aio_suspend() 6.7.8 */
 /* TODO: aio_fsync() 6.7.9 */
 
-/* 7.1 General Terminal Interface ********************************************/
+/**# General Terminal Interface **********************************************/
 
 /* TODO: cfgetispeed(), cfgetospeed(), cfsetispeed(), cfsetospeed() 7.1.3 */
 /* TODO: tcgetattr(), tcsetattr() 7.2.1 */
 /* TODO: tcsendbreak(), tcdrain(), tcflush(), tcflow() 7.2.2 */
 
+/**% tcgetpgrp
+ * retval = tcgetpgrp(filedes);
+ * retval, errno = tcgetpgrp(filedes)
+ */
 static int
 luxio_tcgetpgrp(lua_State *L) /* 7.2.3 */
 {
@@ -1450,6 +1650,10 @@ luxio_tcgetpgrp(lua_State *L) /* 7.2.3 */
 	return 2;
 }
 
+/**% tcsetpgrp
+ * retval = tcsetpgrp(filedes, pgrp_id);
+ * retval = tcsetpgrp(filedes, pgrp_id)
+ */
 static int
 luxio_tcsetpgrp(lua_State *L) /* 7.2.4 */
 {
@@ -1489,11 +1693,15 @@ luxio_tcsetpgrp(lua_State *L) /* 7.2.4 */
 
 /* TODO: all of this. */
 
-/* 14.2 Clock and timer functions ********************************************/
+/**# Clock and timer functions ***********************************************/
 
 /* TODO: clock_settime(), clock_gettime(), clock_getres() 14.2.1 */
 /* Timer functions excluded, based on signals */
 
+/**% nanosleep
+ * retval = nanosleep(req_timespec, rem_timespec);
+ * retval, errno, rem_sec, rem_nsec = nanosleep(req_sec, req_nsec)
+ */
 static int
 luxio_nanosleep(lua_State *L) /* 14.2.5 */
 {