libs/nixio/docsrc/nixio.lua

   1 --- General POSIX IO library.
   2 module "nixio"
   3
   4 --- Look up a hostname and service via DNS.
   5 -- @class function
   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>
  15 -- </ul>
  16
  17 --- Reverse look up an IP-Address via DNS.
  18 -- @class function
  19 -- @name nixio.getnameinfo
  20 -- @param ipaddr        IPv4 or IPv6-Address
  21 -- @return      FQDN
  22
  23 --- (Linux, BSD) Get a list of available network interfaces and their addresses.
  24 -- @class function
  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>
  38 -- </ul>
  39
  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.
  46 -- @class function
  47 -- @name nixio.bind
  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
  53
  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().
  58 -- @class function
  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
  65
  66 --- Open a file.
  67 -- @class function
  68 -- @name nixio.open
  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).
  75 -- @see nixio.umask
  76 -- @see nixio.open_flags
  77 -- @return      File Object
  78
  79 --- Generate flags for a call to open().
  80 -- @class function
  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
  89
  90 --- Duplicate a file descriptor.
  91 -- @class function
  92 -- @name nixio.dup
  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
  97
  98 --- Create a pipe.
  99 -- @class function
 100 -- @name nixio.pipe
 101 -- @return      File Object of the read end
 102 -- @return      File Object of the write end
 103
 104 --- Get the last system error code.
 105 -- @class function
 106 -- @name nixio.errno
 107 -- @return      Error code
 108
 109 --- Get the error message for the corresponding error code.
 110 -- @class function
 111 -- @name nixio.strerror
 112 -- @param errno System error code
 113 -- @return      Error message
 114
 115 --- Sleep for a specified amount of time.
 116 -- @class function
 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
 123 -- @return true
 124
 125 --- Generate events-bitfield or parse revents-bitfield for poll.
 126 -- @class function
 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 [-"-]
 131 -- @see nixio.poll
 132 -- @return table with boolean fields reflecting the mode parameter
 133 -- <strong>OR</strong> bitfield to use for the events-Flag field
 134
 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.
 138 -- @class function
 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
 145 -- socket instead.
 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>
 152 -- </ul>
 153 -- @param timeout Timeout in milliseconds
 154 -- @name nixio.poll
 155 -- @see nixio.poll_flags
 156 -- @return number of ready IO descriptors
 157 -- @return the fds-table with revents-fields set
 158
 159 --- (POSIX) Clone the current process.
 160 -- @class function
 161 -- @name nixio.fork
 162 -- @return      the child process id for the parent process, 0 for the child process
 163
 164 --- (POSIX) Send a signal to one or more processes.
 165 -- @class function
 166 -- @name nixio.kill
 167 -- @param       target  Target process of process group.
 168 -- @param       signal  Signal to send
 169 -- @return      true
 170
 171 --- (POSIX) Get the parent process id of the current process.
 172 -- @class function
 173 -- @name nixio.getppid
 174 -- @return      parent process id
 175
 176 --- (POSIX) Get the user id of the current process.
 177 -- @class function
 178 -- @name nixio.getuid
 179 -- @return      process user id
 180
 181 --- (POSIX) Get the group id of the current process.
 182 -- @class function
 183 -- @name nixio.getgid
 184 -- @return      process group id
 185
 186 --- (POSIX) Set the group id of the current process.
 187 -- @class function
 188 -- @name nixio.setgid
 189 -- @param gid New Group ID
 190 -- @return      true
 191
 192 --- (POSIX) Set the user id of the current process.
 193 -- @class function
 194 -- @name nixio.setuid
 195 -- @param gid New User ID
 196 -- @return      true
 197
 198 --- (POSIX) Change priority of current process.
 199 -- @class function
 200 -- @name nixio.nice
 201 -- @param nice Nice Value
 202 -- @return      true
 203
 204 --- (POSIX) Create a new session and set the process group ID.
 205 -- @class function
 206 -- @name nixio.setsid
 207 -- @return      session id
 208
 209 --- (POSIX) Wait for a process to change state.
 210 -- @class function
 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]
 219
 220 --- (POSIX) Get process times.
 221 -- @class function
 222 -- @name nixio.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>
 228 -- </ul>
 229
 230 --- (POSIX) Get information about current system and kernel.
 231 -- @class function
 232 -- @name nixio.uname
 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>
 239 -- </ul>
 240
 241 --- Change the working directory.
 242 -- @class function
 243 -- @name nixio.chdir
 244 -- @param       path New working directory
 245 -- @return true
 246
 247 --- Ignore or use set the default handler for a signal.
 248 -- @class function
 249 -- @name nixio.signal
 250 -- @param signal        Signal
 251 -- @param handler       ["ign", "dfl"]
 252 -- @return true
 253
 254 --- Get the ID of the current process.
 255 -- @class function
 256 -- @name nixio.getpid
 257 -- @return process id
 258
 259 --- Get the current working directory.
 260 -- @class function
 261 -- @name nixio.getcwd
 262 -- @return workign directory
 263
 264 --- Get the current environment table or a specific environment variable.
 265 -- @class function
 266 -- @name nixio.getenv
 267 -- @param variable Variable (optional)
 268 -- @return environment table or single environment variable
 269
 270 --- Set or unset a environment variable.
 271 -- @class function
 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)
 276 -- @return true
 277
 278 --- Execute a file to replace the current process.
 279 -- @class function
 280 -- @name nixio.exec
 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
 285
 286 --- Invoke the shell and execute a file to replace the current process.
 287 -- @class function
 288 -- @name nixio.execp
 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
 293
 294 --- Execute a file with a custom environment to replace the current process.
 295 -- @class function
 296 -- @name nixio.exece
 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)
 302
 303 --- Sets the file mode creation mask.
 304 -- @class function
 305 -- @name nixio.umask
 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
 309
 310 --- (Linux) Get overall system statistics.
 311 -- @class function
 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>
 323 -- </ul>
 324
 325 --- Create a new socket.
 326 -- @class function
 327 -- @name nixio.socket
 328 -- @param domain        Domain ["inet", "inet6", "unix"]
 329 -- @param type          Type   ["stream", "dgram", "raw"]
 330 -- @return      Socket Object
 331
 332 --- (POSIX) Send data from a file to a socket in kernel-space.
 333 -- @class function
 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
 339
 340 --- (Linux) Send data from / to a pipe in kernel-space.
 341 -- @class function
 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
 349
 350 --- (Linux) Generate a flag bitfield for a call to splice.
 351 -- @class function
 352 -- @name nixio.splice_flags
 353 -- @param flag1 First Flag      ["move", "nonblock", "more"]
 354 -- @param ...   More flags      [-"-]
 355 -- @see nixio.splice
 356 -- @return Flag bitfield
 357
 358 --- (POSIX) Open a connection to the system logger.
 359 -- @class function
 360 -- @name nixio.openlog
 361 -- @param ident Identifier
 362 -- @param flag1 Flag 1 ["cons", "nowait", "pid", "perror", "ndelay", "odelay"]
 363 -- @param ...   More flags [-"-]
 364
 365 --- (POSIX) Close the connection to the system logger.
 366 -- @class function
 367 -- @name nixio.closelog
 368
 369 --- (POSIX) Write a message to the system logger.
 370 -- @class function
 371 -- @name nixio.syslog
 372 -- @param priority Priority ["emerg", "alert", "crit", "err", "warning",
 373 -- "notice", "info", "debug"]
 374 -- @param message
 375
 376 --- (POSIX) Set the logmask of the system logger for current process.
 377 -- @class function
 378 -- @name nixio.setlogmask
 379 -- @param priority Priority ["emerg", "alert", "crit", "err", "warning",
 380 -- "notice", "info", "debug"]
 381
 382 --- (POSIX) Encrypt a user password.
 383 -- @class function
 384 -- @name nixio.crypt
 385 -- @param key Key
 386 -- @param salt Salt
 387 -- @return password hash
 388
 389 --- (POSIX) Get all or a specific user group.
 390 -- @class function
 391 -- @name nixio.getgr
 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>
 398 -- </ul>
 399
 400 --- (POSIX) Get all or a specific user account.
 401 -- @class function
 402 -- @name nixio.getpw
 403 -- @param user User ID or username (optional)
 404 -- @return Table containing: <ul>
 405 -- <li>name = Name</li>
 406 -- <li>uid = ID</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>
 412 -- </ul>
 413
 414 --- (Linux, Solaris) Get all or a specific shadow password entry.
 415 -- @class function
 416 -- @name nixio.getsp
 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>
 428 -- </ul>
 429
 430 --- Create a new TLS context.
 431 -- @class function
 432 -- @name nixio.tls
 433 -- @return TLSContext Object