nixio.lua 15 KB

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