1 --- General POSIX IO library.
4 --- Look up a hostname and service via DNS.
6 -- @name nixio.getaddrinfo
7 -- @param host hostname to lookup (optional)
8 -- @param family address family [<strong>"any"</strong>, "inet", "inet6"]
9 -- @param service service name or port (optional)
10 -- @return Table containing one or more tables containing: <ul>
11 -- <li>family = ["inet", "inet6"]</li>
12 -- <li>socktype = ["stream", "dgram", "raw"]</li>
13 -- <li>address = Resolved IP-Address</li>
14 -- <li>port = Resolved Port (if service was given)</li>
17 --- Reverse look up an IP-Address via DNS.
19 -- @name nixio.getnameinfo
20 -- @param ipaddr IPv4 or IPv6-Address
23 --- (Linux, BSD) Get a list of available network interfaces and their addresses.
25 -- @name nixio.getifaddrs
26 -- @return Table containing one or more tables containing: <ul>
27 -- <li>name = Interface Name</li>
28 -- <li>family = ["inet", "inet6", "packet"]</li>
29 -- <li>addr = Interface Address (IPv4, IPv6, MAC, ...)</li>
30 -- <li>broadaddr = Broadcast Address</li>
31 -- <li>dstaddr = Destination Address (Point-to-Point)</li>
32 -- <li>netmask = Netmask (if available)</li>
33 -- <li>prefix = Prefix (if available)</li>
34 -- <li>flags = Table of interface flags (up, multicast, loopback, ...)</li>
35 -- <li>data = Statistics (Linux, "packet"-family)</li>
36 -- <li>hatype = Hardware Type Identifier (Linix, "packet"-family)</li>
37 -- <li>ifindex = Interface Index (Linux, "packet"-family)</li>
40 --- Create a new socket and bind it to a network address.
41 -- This function is a shortcut for calling nixio.socket and then bind()
42 -- on the socket object.
43 -- @usage This functions calls getaddrinfo(), socket(),
44 -- setsockopt() and bind() but NOT listen().
45 -- @usage The <em>reuseaddr</em>-option is automatically set before binding.
48 -- @param host Hostname or IP-Address (optional, default: all addresses)
49 -- @param port Port or service description
50 -- @param family Address family [<strong>"any"</strong>, "inet", "inet6"]
51 -- @param socktype Socket Type [<strong>"stream"</strong>, "dgram"]
52 -- @return Socket Object
54 --- Create a new socket and connect to a network address.
55 -- This function is a shortcut for calling nixio.socket and then connect()
56 -- on the socket object.
57 -- @usage This functions calls getaddrinfo(), socket() and connect().
59 -- @name nixio.connect
60 -- @param host Hostname or IP-Address (optional, default: localhost)
61 -- @param port Port or service description
62 -- @param family Address family [<strong>"any"</strong>, "inet", "inet6"]
63 -- @param socktype Socket Type [<strong>"stream"</strong>, "dgram"]
64 -- @return Socket Object
69 -- @usage Although this function also supports the traditional fopen()
70 -- file flags it does not create a file stream but uses the open() syscall.
71 -- @param path Filesystem path to open
72 -- @param flags Flag string or number (see open_flags).
73 -- [<strong>"r"</strong>, "r+", "w", "w+", "a", "a+"]
74 -- @param mode File mode for newly created files (see chmod, umask).
76 -- @see nixio.open_flags
77 -- @return File Object
79 --- Generate flags for a call to open().
81 -- @name nixio.open_flags
82 -- @usage This function cannot fail and will never return nil.
83 -- @usage The "nonblock" and "ndelay" flags are aliases.
84 -- @usage The "nonblock", "ndelay" and "sync" flags are no-ops on Windows.
85 -- @param flag1 First Flag ["append", "creat", "excl", "nonblock", "ndelay",
86 -- "sync", "trunc", "rdonly", "wronly", "rdwr"]
87 -- @param ... More Flags [-"-]
88 -- @return flag to be used as second paramter to open
90 --- Duplicate a file descriptor.
93 -- @usage This funcation calls dup2() if <em>newfd</em> is set, otherwise dup().
94 -- @param oldfd Old descriptor [File Object, Socket Object (POSIX only)]
95 -- @param newfd New descriptor to serve as copy (optional)
96 -- @return File Object of new descriptor
101 -- @return File Object of the read end
102 -- @return File Object of the write end
104 --- Get the last system error code.
107 -- @return Error code
109 --- Get the error message for the corresponding error code.
111 -- @name nixio.strerror
112 -- @param errno System error code
113 -- @return Error message
115 --- Sleep for a specified amount of time.
117 -- @usage Not all systems support nanosecond precision but you can expect
118 -- to have at least maillisecond precision.
119 -- @usage This function is not signal-protected and may fail with EINTR.
120 -- @param seconds Seconds to wait (optional)
121 -- @param nanoseconds Nanoseconds to wait (optional)
122 -- @name nixio.nanosleep
125 --- Generate events-bitfield or parse revents-bitfield for poll.
127 -- @name nixio.poll_flags
128 -- @param mode1 revents-Flag bitfield returned from poll to parse OR
129 -- ["in", "out", "err", "pri" (POSIX), "hup" (POSIX), "nval" (POSIX)]
130 -- @param ... More mode strings for generating the flag [-"-]
132 -- @return table with boolean fields reflecting the mode parameter
133 -- <strong>OR</strong> bitfield to use for the events-Flag field
135 --- Wait for some event on a file descriptor.
136 -- poll() sets the revents-field of the tables provided by fds to a bitfield
137 -- indicating the events that occured.
139 -- @usage This function works in-place on the provided table and only
140 -- writes the revents field, you can use other fields on your demand.
141 -- @usage All metamethods on the tables provided as fds are ignored.
142 -- @usage The revents-fields are not reset when the call times out.
143 -- You have to check the first return value to be 0 to handle this case.
144 -- @usage If you want to wait on a TLS-Socket you have to use the underlying
146 -- @usage On Windows poll is emulated through select(), can only be used
147 -- on socket descriptors and cannot take more than 64 descriptors per call.
148 -- @usage This function is not signal-protected and may fail with EINTR.
149 -- @param fds Table containing one or more tables containing <ul>
150 -- <li> fd = I/O Descriptor [Socket Object, File Object (POSIX)]</li>
151 -- <li> events = events to wait for (bitfield generated with poll_flags)</li>
153 -- @param timeout Timeout in milliseconds
155 -- @see nixio.poll_flags
156 -- @return number of ready IO descriptors
157 -- @return the fds-table with revents-fields set
159 --- (POSIX) Clone the current process.
162 -- @return the child process id for the parent process, 0 for the child process
164 --- (POSIX) Send a signal to one or more processes.
167 -- @param target Target process of process group.
168 -- @param signal Signal to send
171 --- (POSIX) Get the parent process id of the current process.
173 -- @name nixio.getppid
174 -- @return parent process id
176 --- (POSIX) Get the user id of the current process.
178 -- @name nixio.getuid
179 -- @return process user id
181 --- (POSIX) Get the group id of the current process.
183 -- @name nixio.getgid
184 -- @return process group id
186 --- (POSIX) Set the group id of the current process.
188 -- @name nixio.setgid
189 -- @param gid New Group ID
192 --- (POSIX) Set the user id of the current process.
194 -- @name nixio.setuid
195 -- @param gid New User ID
198 --- (POSIX) Change priority of current process.
201 -- @param nice Nice Value
204 --- (POSIX) Create a new session and set the process group ID.
206 -- @name nixio.setsid
207 -- @return session id
209 --- (POSIX) Wait for a process to change state.
211 -- @name nixio.waitpid
212 -- @usage If the "nohang" is given this function becomes non-blocking.
213 -- @param pid Process ID (optional, default: any childprocess)
214 -- @param flag1 Flag (optional) ["nohang", "untraced", "continued"]
215 -- @param ... More Flags [-"-]
216 -- @return process id of child or 0 if no child has changed state
217 -- @return ["exited", "signaled", "stopped"]
218 -- @return [exit code, terminate signal, stop signal]
220 --- (POSIX) Get process times.
223 -- @return Table containing: <ul>
224 -- <li>utime = user time</li>
225 -- <li>utime = system time</li>
226 -- <li>cutime = children user time</li>
227 -- <li>cstime = children system time</li>
230 --- (POSIX) Get information about current system and kernel.
233 -- @return Table containing: <ul>
234 -- <li>sysname = operating system</li>
235 -- <li>nodename = network name (usually hostname)</li>
236 -- <li>release = OS release</li>
237 -- <li>version = OS version</li>
238 -- <li>machine = hardware identifier</li>
241 --- Change the working directory.
244 -- @param path New working directory
247 --- Ignore or use set the default handler for a signal.
249 -- @name nixio.signal
250 -- @param signal Signal
251 -- @param handler ["ign", "dfl"]
254 --- Get the ID of the current process.
256 -- @name nixio.getpid
257 -- @return process id
259 --- Get the current working directory.
261 -- @name nixio.getcwd
262 -- @return workign directory
264 --- Get the current environment table or a specific environment variable.
266 -- @name nixio.getenv
267 -- @param variable Variable (optional)
268 -- @return environment table or single environment variable
270 --- Set or unset a environment variable.
272 -- @name nixio.setenv
273 -- @usage The environment variable will be unset if value is ommited.
274 -- @param variable Variable
275 -- @param value Value (optional)
278 --- Execute a file to replace the current process.
281 -- @usage The name of the executable is automatically passed as argv[0]
282 -- @usage This function does not return on success.
283 -- @param executable Executable
284 -- @param ... Parameters
286 --- Invoke the shell and execute a file to replace the current process.
289 -- @usage The name of the executable is automatically passed as argv[0]
290 -- @usage This function does not return on success.
291 -- @param executable Executable
292 -- @param ... Parameters
294 --- Execute a file with a custom environment to replace the current process.
297 -- @usage The name of the executable is automatically passed as argv[0]
298 -- @usage This function does not return on success.
299 -- @param executable Executable
300 -- @param arguments Argument Table
301 -- @param environment Environment Table (optional)
303 --- Sets the file mode creation mask.
306 -- @param mask New creation mask (see chmod for format specifications)
307 -- @return the old umask as decimal mode number
308 -- @return the old umask as mode string
310 --- (Linux) Get overall system statistics.
312 -- @name nixio.sysinfo
313 -- @return Table containing: <ul>
314 -- <li>uptime = system uptime in seconds</li>
315 -- <li>loads = {loadavg1, loadavg5, loadavg15}</li>
316 -- <li>totalram = total RAM</li>
317 -- <li>freeram = free RAM</li>
318 -- <li>sharedram = shared RAM</li>
319 -- <li>bufferram = buffered RAM</li>
320 -- <li>totalswap = total SWAP</li>
321 -- <li>freeswap = free SWAP</li>
322 -- <li>procs = number of running processes</li>
325 --- Create a new socket.
327 -- @name nixio.socket
328 -- @param domain Domain ["inet", "inet6", "unix"]
329 -- @param type Type ["stream", "dgram", "raw"]
330 -- @return Socket Object
332 --- (POSIX) Send data from a file to a socket in kernel-space.
334 -- @name nixio.sendfile
335 -- @param socket Socket Object
336 -- @param file File Object
337 -- @param length Amount of data to send (in Bytes).
338 -- @return bytes sent
340 --- (Linux) Send data from / to a pipe in kernel-space.
342 -- @name nixio.splice
343 -- @param fdin Input I/O descriptor
344 -- @param fdout Output I/O descriptor
345 -- @param length Amount of data to send (in Bytes).
346 -- @param flags (optional, bitfield generated by splice_flags)
347 -- @see nixio.splice_flags
348 -- @return bytes sent
350 --- (Linux) Generate a flag bitfield for a call to splice.
352 -- @name nixio.splice_flags
353 -- @param flag1 First Flag ["move", "nonblock", "more"]
354 -- @param ... More flags [-"-]
356 -- @return Flag bitfield
358 --- (POSIX) Open a connection to the system logger.
360 -- @name nixio.openlog
361 -- @param ident Identifier
362 -- @param flag1 Flag 1 ["cons", "nowait", "pid", "perror", "ndelay", "odelay"]
363 -- @param ... More flags [-"-]
365 --- (POSIX) Close the connection to the system logger.
367 -- @name nixio.closelog
369 --- (POSIX) Write a message to the system logger.
371 -- @name nixio.syslog
372 -- @param priority Priority ["emerg", "alert", "crit", "err", "warning",
373 -- "notice", "info", "debug"]
376 --- (POSIX) Set the logmask of the system logger for current process.
378 -- @name nixio.setlogmask
379 -- @param priority Priority ["emerg", "alert", "crit", "err", "warning",
380 -- "notice", "info", "debug"]
382 --- (POSIX) Encrypt a user password.
387 -- @return password hash
389 --- (POSIX) Get all or a specific user group.
392 -- @param group Group ID or groupname (optional)
393 -- @return Table containing: <ul>
394 -- <li>name = Group Name</li>
395 -- <li>gid = Group ID</li>
396 -- <li>passwd = Password</li>
397 -- <li>mem = {Member #1, Member #2, ...}</li>
400 --- (POSIX) Get all or a specific user account.
403 -- @param user User ID or username (optional)
404 -- @return Table containing: <ul>
405 -- <li>name = Name</li>
407 -- <li>gid = Group ID</li>
408 -- <li>passwd = Password</li>
409 -- <li>dir = Home directory</li>
410 -- <li>gecos = Information</li>
411 -- <li>shell = Shell</li>
414 --- (Linux, Solaris) Get all or a specific shadow password entry.
417 -- @param user username (optional)
418 -- @return Table containing: <ul>
419 -- <li>namp = Name</li>
420 -- <li>expire = Expiration Date</li>
421 -- <li>flag = Flags</li>
422 -- <li>inact = Inactivity Date</li>
423 -- <li>lstchg = Last change</li>
424 -- <li>max = Maximum</li>
425 -- <li>min = Minimum</li>
426 -- <li>warn = Warning</li>
427 -- <li>pwdp = Password Hash</li>
430 --- Create a new TLS context.
433 -- @return TLSContext Object