libs/luci-lib-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 --- Get protocol entry by name.
  41 -- @usage This function returns nil if the given protocol is unknown.
  42 -- @class function
  43 -- @name nixio.getprotobyname
  44 -- @param name          protocol name to lookup
  45 -- @return                      Table containing the following fields: <ul>
  46 -- <li>name = Protocol Name</li>
  47 -- <li>proto = Protocol Number</li>
  48 -- <li>aliases = Table of alias names</li>
  49 -- </ul>
  50
  51 --- Get protocol entry by number.
  52 -- @usage This function returns nil if the given protocol is unknown.
  53 -- @class function
  54 -- @name nixio.getprotobynumber
  55 -- @param proto         protocol number to lookup
  56 -- @return                      Table containing the following fields: <ul>
  57 -- <li>name = Protocol Name</li>
  58 -- <li>proto = Protocol Number</li>
  59 -- <li>aliases = Table of alias names</li>
  60 -- </ul>
  61
  62 --- Get all or a specifc proto entry.
  63 -- @class function
  64 -- @name nixio.getproto
  65 -- @param proto         protocol number or name to lookup (optional)
  66 -- @return                      Table (or if no parameter is given, a table of tables)
  67 --                  containing the following fields: <ul>
  68 -- <li>name = Protocol Name</li>
  69 -- <li>proto = Protocol Number</li>
  70 -- <li>aliases = Table of alias names</li>
  71 -- </ul>
  72
  73 --- Create a new socket and bind it to a network address.
  74 -- This function is a shortcut for calling nixio.socket and then bind()
  75 -- on the socket object.
  76 -- @usage This functions calls getaddrinfo(), socket(),
  77 -- setsockopt() and bind() but NOT listen().
  78 -- @usage The <em>reuseaddr</em>-option is automatically set before binding.
  79 -- @class function
  80 -- @name nixio.bind
  81 -- @param host  Hostname or IP-Address (optional, default: all addresses)
  82 -- @param port  Port or service description
  83 -- @param family Address family [<strong>"any"</strong>, "inet", "inet6"]
  84 -- @param socktype Socket Type [<strong>"stream"</strong>, "dgram"]
  85 -- @return      Socket Object
  86
  87 --- Create a new socket and connect to a network address.
  88 -- This function is a shortcut for calling nixio.socket and then connect()
  89 -- on the socket object.
  90 -- @usage This functions calls getaddrinfo(), socket() and connect().
  91 -- @class function
  92 -- @name nixio.connect
  93 -- @param host  Hostname or IP-Address (optional, default: localhost)
  94 -- @param port  Port or service description
  95 -- @param family Address family [<strong>"any"</strong>, "inet", "inet6"]
  96 -- @param socktype Socket Type [<strong>"stream"</strong>, "dgram"]
  97 -- @return      Socket Object
  98
  99 --- Open a file.
 100 -- @class function
 101 -- @name nixio.open
 102 -- @usage Although this function also supports the traditional fopen()
 103 -- file flags it does not create a file stream but uses the open() syscall.
 104 -- @param path  Filesystem path to open
 105 -- @param flags Flag string or number (see open_flags).
 106 -- [<strong>"r"</strong>, "r+", "w", "w+", "a", "a+"]
 107 -- @param  mode File mode for newly created files (see chmod, umask).
 108 -- @see nixio.umask
 109 -- @see nixio.open_flags
 110 -- @return      File Object
 111
 112 --- Generate flags for a call to open().
 113 -- @class function
 114 -- @name nixio.open_flags
 115 -- @usage This function cannot fail and will never return nil.
 116 -- @usage The "nonblock" and "ndelay" flags are aliases.
 117 -- @usage The "nonblock", "ndelay" and "sync" flags are no-ops on Windows.
 118 -- @param flag1 First Flag ["append", "creat", "excl", "nonblock", "ndelay",
 119 -- "sync", "trunc", "rdonly", "wronly", "rdwr"]
 120 -- @param ...   More Flags [-"-]
 121 -- @return flag to be used as second paramter to open
 122
 123 --- Duplicate a file descriptor.
 124 -- @class function
 125 -- @name nixio.dup
 126 -- @usage This funcation calls dup2() if <em>newfd</em> is set, otherwise dup().
 127 -- @param oldfd Old descriptor [File Object, Socket Object (POSIX only)]
 128 -- @param newfd New descriptor to serve as copy (optional)
 129 -- @return      File Object of new descriptor
 130
 131 --- Create a pipe.
 132 -- @class function
 133 -- @name nixio.pipe
 134 -- @return      File Object of the read end
 135 -- @return      File Object of the write end
 136
 137 --- Get the last system error code.
 138 -- @class function
 139 -- @name nixio.errno
 140 -- @return      Error code
 141
 142 --- Get the error message for the corresponding error code.
 143 -- @class function
 144 -- @name nixio.strerror
 145 -- @param errno System error code
 146 -- @return      Error message
 147
 148 --- Sleep for a specified amount of time.
 149 -- @class function
 150 -- @usage Not all systems support nanosecond precision but you can expect
 151 -- to have at least maillisecond precision.
 152 -- @usage This function is not signal-protected and may fail with EINTR.
 153 -- @param seconds Seconds to wait (optional)
 154 -- @param nanoseconds Nanoseconds to wait (optional)
 155 -- @name nixio.nanosleep
 156 -- @return true
 157
 158 --- Generate events-bitfield or parse revents-bitfield for poll.
 159 -- @class function
 160 -- @name nixio.poll_flags
 161 -- @param       mode1   revents-Flag bitfield returned from poll to parse OR
 162 -- ["in", "out", "err", "pri" (POSIX), "hup" (POSIX), "nval" (POSIX)]
 163 -- @param       ...             More mode strings for generating the flag [-"-]
 164 -- @see nixio.poll
 165 -- @return table with boolean fields reflecting the mode parameter
 166 -- <strong>OR</strong> bitfield to use for the events-Flag field
 167
 168 --- Wait for some event on a file descriptor.
 169 -- poll() sets the revents-field of the tables provided by fds to a bitfield
 170 -- indicating the events that occured.
 171 -- @class function
 172 -- @usage This function works in-place on the provided table and only
 173 -- writes the revents field, you can use other fields on your demand.
 174 -- @usage All metamethods on the tables provided as fds are ignored.
 175 -- @usage The revents-fields are not reset when the call times out.
 176 -- You have to check the first return value to be 0 to handle this case.
 177 -- @usage If you want to wait on a TLS-Socket you have to use the underlying
 178 -- socket instead.
 179 -- @usage On Windows poll is emulated through select(), can only be used
 180 -- on socket descriptors and cannot take more than 64 descriptors per call.
 181 -- @usage This function is not signal-protected and may fail with EINTR.
 182 -- @param fds   Table containing one or more tables containing <ul>
 183 -- <li> fd = I/O Descriptor [Socket Object, File Object (POSIX)]</li>
 184 -- <li> events = events to wait for (bitfield generated with poll_flags)</li>
 185 -- </ul>
 186 -- @param timeout Timeout in milliseconds
 187 -- @name nixio.poll
 188 -- @see nixio.poll_flags
 189 -- @return number of ready IO descriptors
 190 -- @return the fds-table with revents-fields set
 191
 192 --- (POSIX) Clone the current process.
 193 -- @class function
 194 -- @name nixio.fork
 195 -- @return      the child process id for the parent process, 0 for the child process
 196
 197 --- (POSIX) Send a signal to one or more processes.
 198 -- @class function
 199 -- @name nixio.kill
 200 -- @param       target  Target process of process group.
 201 -- @param       signal  Signal to send
 202 -- @return      true
 203
 204 --- (POSIX) Get the parent process id of the current process.
 205 -- @class function
 206 -- @name nixio.getppid
 207 -- @return      parent process id
 208
 209 --- (POSIX) Get the user id of the current process.
 210 -- @class function
 211 -- @name nixio.getuid
 212 -- @return      process user id
 213
 214 --- (POSIX) Get the group id of the current process.
 215 -- @class function
 216 -- @name nixio.getgid
 217 -- @return      process group id
 218
 219 --- (POSIX) Set the group id of the current process.
 220 -- @class function
 221 -- @name nixio.setgid
 222 -- @param gid New Group ID
 223 -- @return      true
 224
 225 --- (POSIX) Set the user id of the current process.
 226 -- @class function
 227 -- @name nixio.setuid
 228 -- @param gid New User ID
 229 -- @return      true
 230
 231 --- (POSIX) Change priority of current process.
 232 -- @class function
 233 -- @name nixio.nice
 234 -- @param nice Nice Value
 235 -- @return      true
 236
 237 --- (POSIX) Create a new session and set the process group ID.
 238 -- @class function
 239 -- @name nixio.setsid
 240 -- @return      session id
 241
 242 --- (POSIX) Wait for a process to change state.
 243 -- @class function
 244 -- @name nixio.waitpid
 245 -- @usage       If the "nohang" is given this function becomes non-blocking.
 246 -- @param pid Process ID        (optional, default: any childprocess)
 247 -- @param flag1 Flag    (optional) ["nohang", "untraced", "continued"]
 248 -- @param ...   More Flags [-"-]
 249 -- @return      process id of child or 0 if no child has changed state
 250 -- @return  ["exited", "signaled", "stopped"]
 251 -- @return  [exit code, terminate signal, stop signal]
 252
 253 --- (POSIX) Get process times.
 254 -- @class function
 255 -- @name nixio.times
 256 -- @return Table containing: <ul>
 257 -- <li>utime = user time</li>
 258 -- <li>utime = system time</li>
 259 -- <li>cutime = children user time</li>
 260 -- <li>cstime = children system time</li>
 261 -- </ul>
 262
 263 --- (POSIX) Get information about current system and kernel.
 264 -- @class function
 265 -- @name nixio.uname
 266 -- @return Table containing: <ul>
 267 -- <li>sysname = operating system</li>
 268 -- <li>nodename = network name (usually hostname)</li>
 269 -- <li>release = OS release</li>
 270 -- <li>version = OS version</li>
 271 -- <li>machine = hardware identifier</li>
 272 -- </ul>
 273
 274 --- Change the working directory.
 275 -- @class function
 276 -- @name nixio.chdir
 277 -- @param       path New working directory
 278 -- @return true
 279
 280 --- Ignore or use set the default handler for a signal.
 281 -- @class function
 282 -- @name nixio.signal
 283 -- @param signal        Signal
 284 -- @param handler       ["ign", "dfl"]
 285 -- @return true
 286
 287 --- Get the ID of the current process.
 288 -- @class function
 289 -- @name nixio.getpid
 290 -- @return process id
 291
 292 --- Get the current working directory.
 293 -- @class function
 294 -- @name nixio.getcwd
 295 -- @return workign directory
 296
 297 --- Get the current environment table or a specific environment variable.
 298 -- @class function
 299 -- @name nixio.getenv
 300 -- @param variable Variable (optional)
 301 -- @return environment table or single environment variable
 302
 303 --- Set or unset a environment variable.
 304 -- @class function
 305 -- @name nixio.setenv
 306 -- @usage The environment variable will be unset if value is ommited.
 307 -- @param variable      Variable
 308 -- @param value         Value (optional)
 309 -- @return true
 310
 311 --- Execute a file to replace the current process.
 312 -- @class function
 313 -- @name nixio.exec
 314 -- @usage The name of the executable is automatically passed as argv[0]
 315 -- @usage This function does not return on success.
 316 -- @param executable Executable
 317 -- @param ... Parameters
 318
 319 --- Invoke the shell and execute a file to replace the current process.
 320 -- @class function
 321 -- @name nixio.execp
 322 -- @usage The name of the executable is automatically passed as argv[0]
 323 -- @usage This function does not return on success.
 324 -- @param executable Executable
 325 -- @param ... Parameters
 326
 327 --- Execute a file with a custom environment to replace the current process.
 328 -- @class function
 329 -- @name nixio.exece
 330 -- @usage The name of the executable is automatically passed as argv[0]
 331 -- @usage This function does not return on success.
 332 -- @param executable Executable
 333 -- @param arguments Argument Table
 334 -- @param environment Environment Table (optional)
 335
 336 --- Sets the file mode creation mask.
 337 -- @class function
 338 -- @name nixio.umask
 339 -- @param mask  New creation mask (see chmod for format specifications)
 340 -- @return the old umask as decimal mode number
 341 -- @return the old umask as mode string
 342
 343 --- (Linux) Get overall system statistics.
 344 -- @class function
 345 -- @name nixio.sysinfo
 346 -- @return Table containing: <ul>
 347 -- <li>uptime = system uptime in seconds</li>
 348 -- <li>loads = {loadavg1, loadavg5, loadavg15}</li>
 349 -- <li>totalram = total RAM</li>
 350 -- <li>freeram = free RAM</li>
 351 -- <li>sharedram = shared RAM</li>
 352 -- <li>bufferram = buffered RAM</li>
 353 -- <li>totalswap = total SWAP</li>
 354 -- <li>freeswap = free SWAP</li>
 355 -- <li>procs = number of running processes</li>
 356 -- </ul>
 357
 358 --- Create a new socket.
 359 -- @class function
 360 -- @name nixio.socket
 361 -- @param domain        Domain ["inet", "inet6", "unix"]
 362 -- @param type          Type   ["stream", "dgram", "raw"]
 363 -- @return      Socket Object
 364
 365 --- (POSIX) Send data from a file to a socket in kernel-space.
 366 -- @class function
 367 -- @name nixio.sendfile
 368 -- @param socket Socket Object
 369 -- @param file   File Object
 370 -- @param length Amount of data to send (in Bytes).
 371 -- @return bytes sent
 372
 373 --- (Linux) Send data from / to a pipe in kernel-space.
 374 -- @class function
 375 -- @name nixio.splice
 376 -- @param fdin  Input I/O descriptor
 377 -- @param fdout Output I/O descriptor
 378 -- @param length Amount of data to send (in Bytes).
 379 -- @param flags (optional, bitfield generated by splice_flags)
 380 -- @see nixio.splice_flags
 381 -- @return bytes sent
 382
 383 --- (Linux) Generate a flag bitfield for a call to splice.
 384 -- @class function
 385 -- @name nixio.splice_flags
 386 -- @param flag1 First Flag      ["move", "nonblock", "more"]
 387 -- @param ...   More flags      [-"-]
 388 -- @see nixio.splice
 389 -- @return Flag bitfield
 390
 391 --- (POSIX) Open a connection to the system logger.
 392 -- @class function
 393 -- @name nixio.openlog
 394 -- @param ident Identifier
 395 -- @param flag1 Flag 1 ["cons", "nowait", "pid", "perror", "ndelay", "odelay"]
 396 -- @param ...   More flags [-"-]
 397
 398 --- (POSIX) Close the connection to the system logger.
 399 -- @class function
 400 -- @name nixio.closelog
 401
 402 --- (POSIX) Write a message to the system logger.
 403 -- @class function
 404 -- @name nixio.syslog
 405 -- @param priority Priority ["emerg", "alert", "crit", "err", "warning",
 406 -- "notice", "info", "debug"]
 407 -- @param message
 408
 409 --- (POSIX) Set the logmask of the system logger for current process.
 410 -- @class function
 411 -- @name nixio.setlogmask
 412 -- @param priority Priority ["emerg", "alert", "crit", "err", "warning",
 413 -- "notice", "info", "debug"]
 414
 415 --- (POSIX) Encrypt a user password.
 416 -- @class function
 417 -- @name nixio.crypt
 418 -- @param key Key
 419 -- @param salt Salt
 420 -- @return password hash
 421
 422 --- (POSIX) Get all or a specific user group.
 423 -- @class function
 424 -- @name nixio.getgr
 425 -- @param group Group ID or groupname (optional)
 426 -- @return Table containing: <ul>
 427 -- <li>name = Group Name</li>
 428 -- <li>gid = Group ID</li>
 429 -- <li>passwd = Password</li>
 430 -- <li>mem = {Member #1, Member #2, ...}</li>
 431 -- </ul>
 432
 433 --- (POSIX) Get all or a specific user account.
 434 -- @class function
 435 -- @name nixio.getpw
 436 -- @param user User ID or username (optional)
 437 -- @return Table containing: <ul>
 438 -- <li>name = Name</li>
 439 -- <li>uid = ID</li>
 440 -- <li>gid = Group ID</li>
 441 -- <li>passwd = Password</li>
 442 -- <li>dir = Home directory</li>
 443 -- <li>gecos = Information</li>
 444 -- <li>shell = Shell</li>
 445 -- </ul>
 446
 447 --- (Linux, Solaris) Get all or a specific shadow password entry.
 448 -- @class function
 449 -- @name nixio.getsp
 450 -- @param user username (optional)
 451 -- @return Table containing: <ul>
 452 -- <li>namp = Name</li>
 453 -- <li>expire = Expiration Date</li>
 454 -- <li>flag = Flags</li>
 455 -- <li>inact = Inactivity Date</li>
 456 -- <li>lstchg = Last change</li>
 457 -- <li>max = Maximum</li>
 458 -- <li>min = Minimum</li>
 459 -- <li>warn = Warning</li>
 460 -- <li>pwdp = Password Hash</li>
 461 -- </ul>
 462
 463 --- Create a new TLS context.
 464 -- @class function
 465 -- @name nixio.tls
 466 -- @param mode TLS-Mode ["client", "server"]
 467 -- @return TLSContext Object