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 --- Create a new socket and bind it to a network address.
24 -- This function is a shortcut for calling nixio.socket and then bind()
25 -- on the socket object.
26 -- @usage This functions calls getaddrinfo(), socket(),
27 -- setsockopt() and bind() but NOT listen().
28 -- @usage The <em>reuseaddr</em>-option is automatically set before binding.
31 -- @param host Hostname or IP-Address (optional, default: all addresses)
32 -- @param port Port or service description
33 -- @param family Address family [<strong>"any"</strong>, "inet", "inet6"]
34 -- @param socktype Socket Type [<strong>"stream"</strong>, "dgram"]
35 -- @return Socket Object
37 --- Create a new socket and connect to a network address.
38 -- This function is a shortcut for calling nixio.socket and then connect()
39 -- on the socket object.
40 -- @usage This functions calls getaddrinfo(), socket() and connect().
42 -- @name nixio.connect
43 -- @param host Hostname or IP-Address (optional, default: localhost)
44 -- @param port Port or service description
45 -- @param family Address family [<strong>"any"</strong>, "inet", "inet6"]
46 -- @param socktype Socket Type [<strong>"stream"</strong>, "dgram"]
47 -- @return Socket Object
52 -- @usage Although this function also supports the traditional fopen()
53 -- file flags it does not create a file stream but uses the open() syscall.
54 -- @param path Filesystem path to open
55 -- @param flags Flag string or number (see open_flags).
56 -- [<strong>"r"</strong>, "r+", "w", "w+", "a", "a+"]
57 -- @param mode File mode for newly created files (see chmod, umask).
59 -- @see nixio.open_flags
60 -- @return File Object
62 --- Generate flags for a call to open().
64 -- @name nixio.open_flags
65 -- @usage This function cannot fail and will never return nil.
66 -- @usage The "nonblock" and "ndelay" flags are aliases.
67 -- @usage The "nonblock", "ndelay" and "sync" flags are no-ops on Windows.
68 -- @param flag1 First Flag ["append", "creat", "excl", "nonblock", "ndelay",
69 -- "sync", "trunc", "rdonly", "wronly", "rdwr"]
70 -- @param ... More Flags [-"-]
71 -- @return flag to be used as second paramter to open
73 --- Duplicate a file descriptor.
76 -- @usage This funcation calls dup2() if <em>newfd</em> is set, otherwise dup().
77 -- @param oldfd Old descriptor [File Object, Socket Object (POSIX only)]
78 -- @param newfd New descriptor to serve as copy (optional)
79 -- @return File Object of new descriptor
84 -- @return File Object of the read end
85 -- @return File Object of the write end
87 --- Get the last system error code.
92 --- Get the error message for the corresponding error code.
94 -- @name nixio.strerror
95 -- @param errno System error code
96 -- @return Error message
98 --- Sleep for a specified amount of time.
100 -- @usage Not all systems support nanosecond precision but you can expect
101 -- to have at least maillisecond precision.
102 -- @usage This function is not signal-protected and may fail with EINTR.
103 -- @param seconds Seconds to wait (optional)
104 -- @param nanoseconds Nanoseconds to wait (optional)
105 -- @name nixio.nanosleep
108 --- Generate events-bitfield or parse revents-bitfield for poll.
110 -- @name nixio.poll_flags
111 -- @param mode1 revents-Flag bitfield returned from poll to parse OR
112 -- ["in", "out", "err", "pri" (POSIX), "hup" (POSIX), "nval" (POSIX)]
113 -- @param ... More mode strings for generating the flag [-"-]
115 -- @return table with boolean fields reflecting the mode parameter
116 -- <strong>OR</strong> bitfield to use for the events-Flag field
118 --- Wait for some event on a file descriptor.
119 -- poll() sets the revents-field of the tables provided by fds to a bitfield
120 -- indicating the events that occured.
122 -- @usage This function works in-place on the provided table and only
123 -- writes the revents field, you can use other fields on your demand.
124 -- @usage All metamethods on the tables provided as fds are ignored.
125 -- @usage The revents-fields are not reset when the call times out.
126 -- You have to check the first return value to be 0 to handle this case.
127 -- @usage If you want to wait on a TLS-Socket you have to use the underlying
129 -- @usage On Windows poll is emulated through select(), can only be used
130 -- on socket descriptors and cannot take more than 64 descriptors per call.
131 -- @usage This function is not signal-protected and may fail with EINTR.
132 -- @param fds Table containing one or more tables containing <ul>
133 -- <li> fd = I/O Descriptor [Socket Object, File Object (POSIX)]</li>
134 -- <li> events = events to wait for (bitfield generated with poll_flags)</li>
136 -- @param timeout Timeout in milliseconds
138 -- @see nixio.poll_flags
139 -- @return number of ready IO descriptors
140 -- @return the fds-table with revents-fields set
142 --- (POSIX) Clone the current process.
145 -- @return the child process id for the parent process, 0 for the child process
147 --- (POSIX) Send a signal to one or more processes.
150 -- @param target Target process of process group.
151 -- @param signal Signal to send
154 --- (POSIX) Get the parent process id of the current process.
156 -- @name nixio.getppid
157 -- @return parent process id
159 --- (POSIX) Get the user id of the current process.
161 -- @name nixio.getuid
162 -- @return process user id
164 --- (POSIX) Get the group id of the current process.
166 -- @name nixio.getgid
167 -- @return process group id
169 --- (POSIX) Set the group id of the current process.
171 -- @name nixio.setgid
172 -- @param gid New Group ID
175 --- (POSIX) Set the user id of the current process.
177 -- @name nixio.setuid
178 -- @param gid New User ID
181 --- (POSIX) Change priority of current process.
184 -- @param nice Nice Value
187 --- (POSIX) Create a new session and set the process group ID.
189 -- @name nixio.setsid
190 -- @return session id
192 --- (POSIX) Wait for a process to change state.
194 -- @name nixio.waitpid
195 -- @usage If the "nohang" is given this function becomes non-blocking.
196 -- @param pid Process ID (optional, default: any childprocess)
197 -- @param flag1 Flag (optional) ["nohang", "untraced", "continued"]
198 -- @param ... More Flags [-"-]
199 -- @return process id of child or 0 if no child has changed state
200 -- @return ["exited", "signaled", "stopped"]
201 -- @return [exit code, terminate signal, stop signal]
203 --- (POSIX) Get process times.
206 -- @return Table containing: <ul>
207 -- <li>utime = user time</li>
208 -- <li>utime = system time</li>
209 -- <li>cutime = children user time</li>
210 -- <li>cstime = children system time</li>
213 --- (POSIX) Get information about current system and kernel.
216 -- @return Table containing: <ul>
217 -- <li>sysname = operating system</li>
218 -- <li>nodename = network name (usually hostname)</li>
219 -- <li>release = OS release</li>
220 -- <li>version = OS version</li>
221 -- <li>machine = hardware identifier</li>
224 --- Change the working directory.
227 -- @param path New working directory
230 --- Ignore or use set the default handler for a signal.
232 -- @name nixio.signal
233 -- @param signal Signal
234 -- @param handler ["ign", "dfl"]
237 --- Get the ID of the current process.
239 -- @name nixio.getpid
240 -- @return process id
242 --- Get the current working directory.
244 -- @name nixio.getcwd
245 -- @return workign directory
247 --- Get the current environment table or a specific environment variable.
249 -- @name nixio.getenv
250 -- @param variable Variable (optional)
251 -- @return environment table or single environment variable
253 --- Set or unset a environment variable.
255 -- @name nixio.setenv
256 -- @usage The environment variable will be unset if value is ommited.
257 -- @param variable Variable
258 -- @param value Value (optional)
261 --- Execute a file to replace the current process.
264 -- @usage The name of the executable is automatically passed as argv[0]
265 -- @usage This function does not return on success.
266 -- @param executable Executable
267 -- @param ... Parameters
269 --- Invoke the shell and execute a file to replace the current process.
272 -- @usage The name of the executable is automatically passed as argv[0]
273 -- @usage This function does not return on success.
274 -- @param executable Executable
275 -- @param ... Parameters
277 --- Execute a file with a custom environment to replace the current process.
280 -- @usage The name of the executable is automatically passed as argv[0]
281 -- @usage This function does not return on success.
282 -- @param executable Executable
283 -- @param arguments Argument Table
284 -- @param environment Environment Table (optional)
286 --- Sets the file mode creation mask.
289 -- @param mask New creation mask (see chmod for format specifications)
290 -- @return the old umask as decimal mode number
291 -- @return the old umask as mode string
293 --- (Linux) Get overall system statistics.
295 -- @name nixio.sysinfo
296 -- @return Table containing: <ul>
297 -- <li>uptime = system uptime in seconds</li>
298 -- <li>loads = {loadavg1, loadavg5, loadavg15}</li>
299 -- <li>totalram = total RAM</li>
300 -- <li>freeram = free RAM</li>
301 -- <li>sharedram = shared RAM</li>
302 -- <li>bufferram = buffered RAM</li>
303 -- <li>totalswap = total SWAP</li>
304 -- <li>freeswap = free SWAP</li>
305 -- <li>procs = number of running processes</li>
308 --- Create a new socket.
310 -- @name nixio.socket
311 -- @param domain Domain ["inet", "inet6", "unix"]
312 -- @param type Type ["stream", "dgram", "raw"]
313 -- @return Socket Object
315 --- (POSIX) Send data from a file to a socket in kernel-space.
317 -- @name nixio.sendfile
318 -- @param socket Socket Object
319 -- @param file File Object
320 -- @param length Amount of data to send (in Bytes).
321 -- @return bytes sent
323 --- (Linux) Send data from / to a pipe in kernel-space.
325 -- @name nixio.splice
326 -- @param fdin Input I/O descriptor
327 -- @param fdout Output I/O descriptor
328 -- @param length Amount of data to send (in Bytes).
329 -- @param flags (optional, bitfield generated by splice_flags)
330 -- @see nixio.splice_flags
331 -- @return bytes sent
333 --- (Linux) Generate a flag bitfield for a call to splice.
335 -- @name nixio.splice_flags
336 -- @param flag1 First Flag ["move", "nonblock", "more"]
337 -- @param ... More flags [-"-]
339 -- @return Flag bitfield
341 --- (POSIX) Open a connection to the system logger.
343 -- @name nixio.openlog
344 -- @param ident Identifier
345 -- @param flag1 Flag 1 ["cons", "nowait", "pid", "perror", "ndelay", "odelay"]
346 -- @param ... More flags [-"-]
348 --- (POSIX) Close the connection to the system logger.
350 -- @name nixio.closelog
352 --- (POSIX) Write a message to the system logger.
354 -- @name nixio.syslog
355 -- @param priority Priority ["emerg", "alert", "crit", "err", "warning",
356 -- "notice", "info", "debug"]
359 --- (POSIX) Set the logmask of the system logger for current process.
361 -- @name nixio.setlogmask
362 -- @param priority Priority ["emerg", "alert", "crit", "err", "warning",
363 -- "notice", "info", "debug"]
365 --- (POSIX) Encrypt a user password.
370 -- @return password hash
372 --- (POSIX) Get all or a specific user group.
375 -- @param group Group ID or groupname (optional)
376 -- @return Table containing: <ul>
377 -- <li>name = Group Name</li>
378 -- <li>gid = Group ID</li>
379 -- <li>passwd = Password</li>
380 -- <li>mem = {Member #1, Member #2, ...}</li>
383 --- (POSIX) Get all or a specific user account.
386 -- @param user User ID or username (optional)
387 -- @return Table containing: <ul>
388 -- <li>name = Name</li>
390 -- <li>gid = Group ID</li>
391 -- <li>passwd = Password</li>
392 -- <li>dir = Home directory</li>
393 -- <li>gecos = Information</li>
394 -- <li>shell = Shell</li>
397 --- (Linux, Solaris) Get all or a specific shadow password entry.
400 -- @param user username (optional)
401 -- @return Table containing: <ul>
402 -- <li>namp = Name</li>
403 -- <li>expire = Expiration Date</li>
404 -- <li>flag = Flags</li>
405 -- <li>inact = Inactivity Date</li>
406 -- <li>lstchg = Last change</li>
407 -- <li>max = Maximum</li>
408 -- <li>min = Minimum</li>
409 -- <li>warn = Warning</li>
410 -- <li>pwdp = Password Hash</li>
413 --- Create a new TLS context.
416 -- @return TLSContext Object