Merge nixio 0.2

1 files changed, 416 insertions, 0 deletions

diff --git a/libs/nixio/docsrc/nixio.lua b/libs/nixio/docsrc/nixio.lua
new file mode 100644
index 000000000..7efeab8ef
--- /dev/null
+++ b/libs/nixio/docsrc/nixio.lua
@@ -0,0 +1,416 @@
+--- General POSIX IO library.
+module "nixio"
+
+--- Look up a hostname and service via DNS.
+-- @class function
+-- @name nixio.getaddrinfo
+-- @param host		hostname to lookup	(optional)
+-- @param family 	address family [<strong>"any"</strong>, "inet", "inet6"]  
+-- @param service	service name or port (optional)
+-- @return			Table containing one or more tables containing: <ul>
+-- <li>family = ["inet", "inet6"]</li>
+-- <li>socktype = ["stream", "dgram", "raw"]</li>
+-- <li>address = Resolved IP-Address</li>
+-- <li>port = Resolved Port (if service was given)</li>
+-- </ul>
+
+--- Reverse look up an IP-Address via DNS.
+-- @class function
+-- @name nixio.getnameinfo
+-- @param ipaddr	IPv4 or IPv6-Address
+-- @return	FQDN
+
+--- Create a new socket and bind it to a network address.
+-- This function is a shortcut for calling nixio.socket and then bind()
+-- on the socket object.
+-- @usage This functions calls getaddrinfo(), socket(),
+-- setsockopt() and bind() but NOT listen().
+-- @usage The <em>reuseaddr</em>-option is automatically set before binding.
+-- @class function
+-- @name nixio.bind
+-- @param host	Hostname or IP-Address (optional, default: all addresses)
+-- @param port	Port or service description
+-- @param family Address family [<strong>"any"</strong>, "inet", "inet6"]
+-- @param socktype Socket Type [<strong>"stream"</strong>, "dgram"]
+-- @return	Socket Object
+
+--- Create a new socket and connect to a network address.
+-- This function is a shortcut for calling nixio.socket and then connect()
+-- on the socket object.
+-- @usage This functions calls getaddrinfo(), socket() and connect().
+-- @class function
+-- @name nixio.connect
+-- @param host	Hostname or IP-Address (optional, default: localhost)
+-- @param port	Port or service description
+-- @param family Address family [<strong>"any"</strong>, "inet", "inet6"]
+-- @param socktype Socket Type [<strong>"stream"</strong>, "dgram"]
+-- @return	Socket Object
+
+--- Open a file.
+-- @class function
+-- @name nixio.open
+-- @usage Although this function also supports the traditional fopen() 
+-- file flags it does not create a file stream but uses the open() syscall.
+-- @param path	Filesystem path to open
+-- @param flags	Flag string or number (see open_flags).
+-- [<strong>"r"</strong>, "r+", "w", "w+", "a", "a+"]
+-- @param  mode	File mode for newly created files (see chmod, umask).
+-- @see	nixio.umask
+-- @see nixio.open_flags
+-- @return	File Object
+
+--- Generate flags for a call to open().
+-- @class function
+-- @name nixio.open_flags
+-- @usage This function cannot fail and will never return nil.
+-- @usage The "nonblock" and "ndelay" flags are aliases.
+-- @usage The "nonblock", "ndelay" and "sync" flags are no-ops on Windows.
+-- @param flag1 First Flag ["append", "creat", "excl", "nonblock", "ndelay",
+-- "sync", "trunc", "rdonly", "wronly", "rdwr"]
+-- @param ...	More Flags [-"-]
+-- @return flag to be used as second paramter to open
+
+--- Duplicate a file descriptor.
+-- @class function
+-- @name nixio.dup
+-- @usage This funcation calls dup2() if <em>newfd</em> is set, otherwise dup().
+-- @param oldfd	Old descriptor [File Object, Socket Object (POSIX only)]
+-- @param newfd New descriptor to serve as copy (optional)
+-- @return	File Object of new descriptor
+
+--- Create a pipe.
+-- @class function
+-- @name nixio.pipe
+-- @return	File Object of the read end
+-- @return	File Object of the write end
+
+--- Get the last system error code.
+-- @class function
+-- @name nixio.errno
+-- @return	Error code
+
+--- Get the error message for the corresponding error code.
+-- @class function
+-- @name nixio.strerror
+-- @param errno System error code
+-- @return	Error message
+
+--- Sleep for a specified amount of time.
+-- @class function
+-- @usage Not all systems support nanosecond precision but you can expect
+-- to have at least maillisecond precision.
+-- @usage This function is not signal-protected and may fail with EINTR.
+-- @param seconds Seconds to wait (optional)
+-- @param nanoseconds Nanoseconds to wait (optional)
+-- @name nixio.nanosleep
+-- @return true
+
+--- Generate events-bitfield or parse revents-bitfield for poll.
+-- @class function
+-- @name nixio.poll_flags
+-- @param	mode1	revents-Flag bitfield returned from poll to parse OR 
+-- ["in", "out", "err", "pri" (POSIX), "hup" (POSIX), "nval" (POSIX)]
+-- @param	...		More mode strings for generating the flag [-"-]
+-- @see nixio.poll
+-- @return table with boolean fields reflecting the mode parameter 
+-- <strong>OR</strong> bitfield to use for the events-Flag field
+
+--- Wait for some event on a file descriptor.
+-- poll() sets the revents-field of the tables provided by fds to a bitfield
+-- indicating the events that occured.
+-- @class function
+-- @usage This function works in-place on the provided table and only
+-- writes the revents field, you can use other fields on your demand.
+-- @usage All metamethods on the tables provided as fds are ignored.
+-- @usage The revents-fields are not reset when the call times out.
+-- You have to check the first return value to be 0 to handle this case.
+-- @usage If you want to wait on a TLS-Socket you have to use the underlying
+-- socket instead.
+-- @usage On Windows poll is emulated through select(), can only be used
+-- on socket descriptors and cannot take more than 64 descriptors per call.
+-- @usage This function is not signal-protected and may fail with EINTR.
+-- @param fds	Table containing one or more tables containing <ul>
+-- <li> fd = I/O Descriptor [Socket Object, File Object (POSIX)]</li>
+-- <li> events = events to wait for (bitfield generated with poll_flags)</li>
+-- </ul>
+-- @param timeout Timeout in milliseconds
+-- @name nixio.poll
+-- @see nixio.poll_flags
+-- @return number of ready IO descriptors
+-- @return the fds-table with revents-fields set
+
+--- (POSIX) Clone the current process.
+-- @class function
+-- @name nixio.fork
+-- @return	the child process id for the parent process, 0 for the child process
+
+--- (POSIX) Send a signal to one or more processes.
+-- @class function
+-- @name nixio.kill
+-- @param	target	Target process of process group.
+-- @param	signal	Signal to send
+-- @return	true
+
+--- (POSIX) Get the parent process id of the current process.
+-- @class function
+-- @name nixio.getppid
+-- @return	parent process id
+
+--- (POSIX) Get the user id of the current process.
+-- @class function
+-- @name nixio.getuid
+-- @return	process user id
+
+--- (POSIX) Get the group id of the current process.
+-- @class function
+-- @name nixio.getgid
+-- @return	process group id
+
+--- (POSIX) Set the group id of the current process.
+-- @class function
+-- @name nixio.setgid
+-- @param gid New Group ID
+-- @return	true
+
+--- (POSIX) Set the user id of the current process.
+-- @class function
+-- @name nixio.setuid
+-- @param gid New User ID
+-- @return	true
+
+--- (POSIX) Change priority of current process.
+-- @class function
+-- @name nixio.nice
+-- @param nice Nice Value
+-- @return	true
+
+--- (POSIX) Create a new session and set the process group ID.
+-- @class function
+-- @name nixio.setsid
+-- @return	session id
+
+--- (POSIX) Wait for a process to change state.
+-- @class function
+-- @name nixio.waitpid
+-- @usage	If the "nohang" is given this function becomes non-blocking.
+-- @param pid Process ID	(optional, default: any childprocess)
+-- @param flag1 Flag	(optional) ["nohang", "untraced", "continued"]
+-- @param ...	More Flags [-"-]
+-- @return	process id of child or 0 if no child has changed state
+-- @return  ["exited", "signaled", "stopped"]
+-- @return  [exit code, terminate signal, stop signal]
+
+--- (POSIX) Get process times.
+-- @class function
+-- @name nixio.times
+-- @return Table containing: <ul>
+-- <li>utime = user time</li>
+-- <li>utime = system time</li>
+-- <li>cutime = children user time</li>
+-- <li>cstime = children system time</li>
+-- </ul>
+
+--- (POSIX) Get information about current system and kernel.
+-- @class function
+-- @name nixio.uname
+-- @return Table containing: <ul>
+-- <li>sysname = operating system</li>
+-- <li>nodename = network name (usually hostname)</li>
+-- <li>release = OS release</li>
+-- <li>version = OS version</li>
+-- <li>machine = hardware identifier</li>
+-- </ul>
+
+--- Change the working directory.
+-- @class function
+-- @name nixio.chdir
+-- @param	path New working directory
+-- @return true
+
+--- Ignore or use set the default handler for a signal.
+-- @class function
+-- @name nixio.signal
+-- @param signal	Signal
+-- @param handler	["ign", "dfl"]
+-- @return true
+
+--- Get the ID of the current process.
+-- @class function
+-- @name nixio.getpid
+-- @return process id
+
+--- Get the current working directory.
+-- @class function
+-- @name nixio.getcwd
+-- @return workign directory
+
+--- Get the current environment table or a specific environment variable.
+-- @class function
+-- @name nixio.getenv
+-- @param variable Variable (optional)
+-- @return environment table or single environment variable
+
+--- Set or unset a environment variable.
+-- @class function
+-- @name nixio.setenv
+-- @usage The environment variable will be unset if value is ommited.
+-- @param variable	Variable
+-- @param value		Value (optional)
+-- @return true
+
+--- Execute a file to replace the current process.
+-- @class function
+-- @name nixio.exec
+-- @usage The name of the executable is automatically passed as argv[0]
+-- @usage This function does not return on success.
+-- @param executable Executable
+-- @param ... Parameters
+
+--- Invoke the shell and execute a file to replace the current process.
+-- @class function
+-- @name nixio.execp
+-- @usage The name of the executable is automatically passed as argv[0]
+-- @usage This function does not return on success.
+-- @param executable Executable
+-- @param ... Parameters
+
+--- Execute a file with a custom environment to replace the current process.
+-- @class function
+-- @name nixio.exece
+-- @usage The name of the executable is automatically passed as argv[0]
+-- @usage This function does not return on success.
+-- @param executable Executable
+-- @param arguments Argument Table
+-- @param environment Environment Table (optional)
+
+--- Sets the file mode creation mask.
+-- @class function
+-- @name nixio.umask
+-- @param mask	New creation mask (see chmod for format specifications)
+-- @return the old umask as decimal mode number
+-- @return the old umask as mode string
+
+--- (Linux) Get overall system statistics.
+-- @class function
+-- @name nixio.sysinfo
+-- @return Table containing: <ul>
+-- <li>uptime = system uptime in seconds</li>
+-- <li>loads = {loadavg1, loadavg5, loadavg15}</li>
+-- <li>totalram = total RAM</li>
+-- <li>freeram = free RAM</li>
+-- <li>sharedram = shared RAM</li>
+-- <li>bufferram = buffered RAM</li>
+-- <li>totalswap = total SWAP</li>
+-- <li>freeswap = free SWAP</li>
+-- <li>procs = number of running processes</li>
+-- </ul>
+
+--- Create a new socket.
+-- @class function
+-- @name nixio.socket
+-- @param domain	Domain ["inet", "inet6", "unix"]
+-- @param type		Type   ["stream", "dgram", "raw"]
+-- @return	Socket Object
+
+--- (POSIX) Send data from a file to a socket in kernel-space.
+-- @class function
+-- @name nixio.sendfile
+-- @param socket Socket Object
+-- @param file	 File Object
+-- @param length Amount of data to send (in Bytes).
+-- @return bytes sent
+
+--- (Linux) Send data from / to a pipe in kernel-space.
+-- @class function
+-- @name nixio.splice
+-- @param fdin	Input I/O descriptor 
+-- @param fdout	Output I/O descriptor
+-- @param length Amount of data to send (in Bytes).
+-- @param flags (optional, bitfield generated by splice_flags)
+-- @see nixio.splice_flags
+-- @return bytes sent
+
+--- (Linux) Generate a flag bitfield for a call to splice.
+-- @class function
+-- @name nixio.splice_flags
+-- @param flag1	First Flag	["move", "nonblock", "more"]
+-- @param ...	More flags	[-"-]
+-- @see nixio.splice
+-- @return Flag bitfield
+
+--- (POSIX) Open a connection to the system logger.
+-- @class function
+-- @name nixio.openlog
+-- @param ident	Identifier
+-- @param flag1	Flag 1 ["cons", "nowait", "pid", "perror", "ndelay", "odelay"]
+-- @param ...	More flags [-"-]
+
+--- (POSIX) Close the connection to the system logger.
+-- @class function
+-- @name nixio.closelog
+
+--- (POSIX) Write a message to the system logger.
+-- @class function
+-- @name nixio.syslog
+-- @param priority Priority ["emerg", "alert", "crit", "err", "warning",
+-- "notice", "info", "debug"]
+-- @param message
+
+--- (POSIX) Set the logmask of the system logger for current process.
+-- @class function
+-- @name nixio.setlogmask
+-- @param priority Priority ["emerg", "alert", "crit", "err", "warning",
+-- "notice", "info", "debug"]
+
+--- (POSIX) Encrypt a user password.
+-- @class function
+-- @name nixio.crypt
+-- @param key Key
+-- @param salt Salt
+-- @return password hash
+
+--- (POSIX) Get all or a specific user group.
+-- @class function
+-- @name nixio.getgr
+-- @param group Group ID or groupname (optional)
+-- @return Table containing: <ul>
+-- <li>name = Group Name</li>
+-- <li>gid = Group ID</li>
+-- <li>passwd = Password</li>
+-- <li>mem = {Member #1, Member #2, ...}</li>
+-- </ul>
+
+--- (POSIX) Get all or a specific user account.
+-- @class function
+-- @name nixio.getpw
+-- @param user User ID or username (optional)
+-- @return Table containing: <ul>
+-- <li>name = Name</li>
+-- <li>uid = ID</li>
+-- <li>gid = Group ID</li>
+-- <li>passwd = Password</li>
+-- <li>dir = Home directory</li>
+-- <li>gecos = Information</li>
+-- <li>shell = Shell</li>
+-- </ul>
+
+--- (Linux, Solaris) Get all or a specific shadow password entry.
+-- @class function
+-- @name nixio.getsp
+-- @param user username (optional)
+-- @return Table containing: <ul>
+-- <li>namp = Name</li>
+-- <li>expire = Expiration Date</li>
+-- <li>flag = Flags</li>
+-- <li>inact = Inactivity Date</li>
+-- <li>lstchg = Last change</li>
+-- <li>max = Maximum</li>
+-- <li>min = Minimum</li>
+-- <li>warn = Warning</li>
+-- <li>pwdp = Password Hash</li>
+-- </ul>
+
+--- Create a new TLS context.
+-- @class function
+-- @name nixio.tls
+-- @return TLSContext Object
\ No newline at end of file