summaryrefslogtreecommitdiff
path: root/luxio.c
diff options
context:
space:
mode:
authorRob Kendrick (plinth) <rjek@rjek.com>2013-12-02 20:26:58 +0000
committerRob Kendrick (plinth) <rjek@rjek.com>2013-12-02 20:26:58 +0000
commit6abd96e7d956f6449c22eabdf1ec299854fce53e (patch)
tree4cd8bf73a8aec2bb21dab4d2693e30a07af0f5fc /luxio.c
parent5c432b5faeefff51b0c56fedd11b4c04267348d4 (diff)
downloadluxio-6abd96e7d956f6449c22eabdf1ec299854fce53e.tar.bz2
More documentation.
Diffstat (limited to 'luxio.c')
-rw-r--r--luxio.c232
1 files changed, 182 insertions, 50 deletions
diff --git a/luxio.c b/luxio.c
index 3832527..24ec720 100644
--- a/luxio.c
+++ b/luxio.c
@@ -2655,10 +2655,13 @@ luxio_shutdown(lua_State *L)
return 2;
}
-/**% connect
- * retval = connect(fd, sockaddr, sockaddrlen);
- * retval, errno = connect(fd, sockaddr)
- */
+/*** Initiate a connection on a socket.
+@tparam number fd
+@tparam sockaddr sockaddr
+@treturn number return value
+@treturn errno
+@function connect
+*/
static int
luxio_connect(lua_State *L)
{
@@ -2672,10 +2675,13 @@ luxio_connect(lua_State *L)
return 2;
}
-/**% bind
- * retval = bind(fd, sockaddr, sockaddrlen);
- * retval, errno = bind(fd, sockaddr)
- */
+/*** Bind a name to a socket.
+@tparam number fd
+@tparam sockaddr sockaddr
+@treturn number return value
+@treturn errno
+@function bind
+*/
static int
luxio_bind(lua_State *L)
{
@@ -2689,11 +2695,12 @@ luxio_bind(lua_State *L)
return 2;
}
-/**% accept
- * retval = accept(fd, sockaddrinfo, sockaddrlen);
- * retval, sockaddr = accept(fd)
- * retval, errno = accept(fd)
- */
+/*** Accept a connection on a socket.
+@tparam number fd
+@treturn number return value
+@treturn errno|sockaddr
+@function accept
+*/
static int
luxio_accept(lua_State *L)
{
@@ -2715,11 +2722,14 @@ luxio_accept(lua_State *L)
return 2;
}
-/**% getsockopt
- * retval = getsockopt(fd, level, optname, optval, optlen);
- * retval, errno = getsockopt(fd, level, optname)
- * retval, opt = getsockopet(fd, level, optname)
- */
+/*** Get options on a socket.
+@tparam number fd
+@tparam number level
+@tparam number optname
+@treturn number return value
+@treturn errno|number|string
+@function getsockopt
+*/
static int
luxio_getsockopt(lua_State *L)
{
@@ -2792,10 +2802,15 @@ luxio_getsockopt(lua_State *L)
return luaL_error(L, "unhandled socket level %d", level);
}
-/**% setsockopt
- * retval = setsockopt(fd, level, optname, optval, optlen);
- * retval, errno = setsockopt(fd, level, optname, optval)
- */
+/*** Set an option on a socket.
+@tparam number fd
+@tparam number level
+@tparam number optname
+@param optvalue
+@treturn number return value
+@treturn errno
+@function setsockopt
+*/
static int
luxio_setsockopt(lua_State *L)
{
@@ -2859,10 +2874,11 @@ luxio_setsockopt(lua_State *L)
return luaL_error(L, "unhandled socket level %d", level);
}
-/**% gai_strerror
- * retval = gai_strerror(errnum);
- * retval = gai_strerror(errno)
- */
+/*** Convert getaddrinfo-specific errors to strings.
+@tparam errno errno
+@treturn string error string
+@function gai_strerror
+*/
static int
luxio_gai_strerror(lua_State *L)
{
@@ -2871,11 +2887,26 @@ luxio_gai_strerror(lua_State *L)
return 1;
}
-/**% getaddrinfo
- * retval = getaddrinfo(node, service, hints, res);
- * errcode = getaddrinfo(node, service[, ai_flags/0, ai_family/AF_UNSPEC, ai_socktype/0, ai_protocol/0])
- * addrinfo = getaddrinfo(node, service[, ai_flags/0, ai_family/AF_UNSPEC, ai_socktype/0, ai_protocol/0])
- */
+/*** Result table from `getaddrinfo`.
+@field ai_flags number
+@field ai_family number
+@field ai_socktype number
+@field ai_protocol number
+@field ai_canonname string
+@field ai_addr sockaddr type containing address information.
+@table addrinfo
+*/
+
+/*** Network address and service translation.
+@tparam string node
+@tparam string service
+@tparam[opt=0] number ai_flags
+@tparam[opt=AF_UNSPEC] number ai_family
+@tparam[opt=0] number ai_socktype
+@tparam[opt=0] number ai_protocol
+@treturn errno|table table of result `addrinfo` entries
+@function getaddrinfo
+*/
static int
luxio_getaddrinfo(lua_State *L)
{
@@ -2940,8 +2971,18 @@ luxio_getaddrinfo(lua_State *L)
return 2;
}
-/* Socket-related send and receive functions *********************************/
+/*** Socket-related send and receive functions.
+@section socksendrecv
+*/
+/*** Send a message on a socket.
+@tparam number fd
+@tparam string data
+@tparam[opt=0] number flags
+@treturn number return value
+@treturn errno
+@function send
+*/
static int
luxio_send(lua_State *L)
{
@@ -2956,6 +2997,15 @@ luxio_send(lua_State *L)
return 2;
}
+/*** Send a message on a socket to a specific destination.
+@tparam number fd
+@tparam string data
+@tparam[opt=0] number flags
+@tparam sockaddr sockaddr
+@treturn number return value
+@treturn errno
+@function sendto
+*/
static int
luxio_sendto(lua_State *L)
{
@@ -2972,6 +3022,14 @@ luxio_sendto(lua_State *L)
return 2;
}
+/*** Receive a message from a socket.
+@tparam number fd
+@tparam number count
+@tparam[opt=0] number flags
+@treturn number|string return value if error, otherwise string
+@treturn errno
+@function recv
+*/
static int
luxio_recv(lua_State *L)
{
@@ -3009,6 +3067,15 @@ luxio_recv(lua_State *L)
return 2;
}
+/*** Receive a message from a socket, also returning sender information.
+@tparam number fd
+@tparam number count
+@tparam[opt=0] number flags
+@treturn number|string return value if error, otherwise string
+@treturn errno
+@treturn sockaddr|nil
+@function recvfrom
+*/
static int
luxio_recvfrom(lua_State *L)
{
@@ -3050,7 +3117,9 @@ luxio_recvfrom(lua_State *L)
return 3;
}
-/* Poll-binding functions ****************************************************/
+/*** Poll-binding functions.
+@section poll
+*/
#define LUXIO_POLLFD_METATABLE "luxio.pollfdarray"
@@ -3179,7 +3248,9 @@ luxio_poll(lua_State *L)
return 2;
}
-/* Bit/flag operation functions **********************************************/
+/*** Bit and flag operation functions.
+@section bit
+*/
static int
luxio_bitop_or(lua_State *L)
@@ -3264,8 +3335,12 @@ luxio_bitop_test(lua_State *L)
return 1;
}
-/* Time-related functions ****************************************************/
-
+/*** Time-related functions.
+The time-related functions in Luxio are medium-rare. A timeval type is exposed
+as a userdata type, complete with comparison, addition/subtraction, and tostring
+metamethods. You can set the fields tv_sec, tv_usec, seconds, and useconds.
+@section time
+*/
#define LUXIO_TIMEVAL_METATABLE "luxio.timeval"
static int
@@ -3420,6 +3495,10 @@ luxio__bless_timeval(lua_State *L)
lua_setmetatable(L, -2);
}
+/*** Create a new timeval, set to the epoch.
+@treturn timeval
+@function zero_timeval
+*/
static int
luxio_timeval_zero(lua_State *L)
{
@@ -3432,6 +3511,11 @@ luxio_timeval_zero(lua_State *L)
return 1;
}
+/*** Get the time of day.
+@treturn timeval|number return value
+@treturn errno
+@function gettimeofday
+*/
static int
luxio_gettimeofday(lua_State *L)
{
@@ -3450,12 +3534,15 @@ luxio_gettimeofday(lua_State *L)
return 1;
}
-/**# Misc utility functions **************************************************/
+/*** Misc utility functions.
+@section misc
+*/
-/**% strerror
- * retval = strerror(errno);
- * retval = strerror(errno)
- */
+/*** Return a string describing an error number.
+@tparam errno
+@treturn string
+@function strerror
+*/
static int
luxio_strerror(lua_State *L)
{
@@ -3466,6 +3553,12 @@ luxio_strerror(lua_State *L)
static char *luxio_openlog_ident = NULL;
+/*** Open a log file.
+@tparam string ident
+@tparam number option
+@tparam number facility
+@function openlog
+*/
static int
luxio_openlog(lua_State *L)
{
@@ -3487,6 +3580,11 @@ luxio_openlog(lua_State *L)
return 0;
}
+/*** Write a message to the open log.
+@tparam number priority
+@tparam string log message
+@function syslog
+*/
static int
luxio_syslog(lua_State *L)
{
@@ -3498,6 +3596,9 @@ luxio_syslog(lua_State *L)
return 0;
}
+/*** Close the open log.
+@function closelog
+*/
static int
luxio_closelog(lua_State *L)
{
@@ -3508,6 +3609,11 @@ luxio_closelog(lua_State *L)
return 0;
}
+/*** Set the log priority mask.
+@tparam number newmask
+@tparam number old mask
+@function setlogmask
+*/
static int
luxio_setlogmask(lua_State *L)
{
@@ -3519,6 +3625,11 @@ luxio_setlogmask(lua_State *L)
return 1;
}
+/*** Discover the bit used for a specific priority.
+@tparam number priority
+@treturn number mask
+@funciton LOG_MASK
+*/
static int
luxio_LOG_MASK(lua_State *L)
{
@@ -3530,6 +3641,13 @@ luxio_LOG_MASK(lua_State *L)
return 1;
}
+/*** Allocate descriptor for character set conversion.
+@tparam string tocode
+@tparam string fromcode
+@treturn iconv|number return value
+@treturn errno
+@function icon_open
+*/
static int
luxio_iconv_open(lua_State *L)
{
@@ -3547,6 +3665,12 @@ luxio_iconv_open(lua_State *L)
}
}
+/*** Close a previously-allocated iconv descriptor.
+@tparam iconv
+@treturn number return vlaue
+@treturn errno
+@function iconv_close
+*/
static int
luxio_iconv_close(lua_State *L)
{
@@ -3564,6 +3688,14 @@ luxio_iconv_close(lua_State *L)
#define ICONV_BUF_SIZE 256
+/*** Perform character set conversion.
+@tparam iconv
+@tparam string
+@treturn string|number resulting string or return value in case of error
+@treturn errno
+@treturn string|nil partial result when error.
+@function iconv
+*/
static int
luxio_iconv(lua_State *L)
{
@@ -3585,15 +3717,15 @@ luxio_iconv(lua_State *L)
if (ret == (size_t)(-1)) {
luaL_addlstring(&b, outbufs, ICONV_BUF_SIZE - obleft);
- if (errno == E2BIG) {
- obleft = ICONV_BUF_SIZE;
- outbuf = outbufs;
- } else {
- lua_pushnumber(L, -1);
- lua_pushnumber(L, errno);
- luaL_pushresult(&b);
- return 3;
- }
+ if (errno == E2BIG) {
+ obleft = ICONV_BUF_SIZE;
+ outbuf = outbufs;
+ } else {
+ lua_pushnumber(L, -1);
+ lua_pushnumber(L, errno);
+ luaL_pushresult(&b);
+ return 3;
+ }
}
} while (ret == (size_t)-1);