[ANN] luaposix 36.0 released

A library binding various POSIX APIs. POSIX is the IEEE Portable Operating System Interface standard. luaposix is based on lposix.

I am happy to announce release 36.0 of luaposix.

This is a pretty big release, and fixes all but a very few known bugs, the largest of which is that numbers requiring more than 32 bits are no longer downcast to C ints across binding boundaries, which makes most bindings work as expected for all but the largest arguments and return values. Of course the magnitude is still limited to the size of lua_Integer in the host Lua!

If you have moved to the new low-level APIs, and don't rely on the Lua backwards compatibility layer and convenience functions, you can safely omit those dependencies and use the C layer only.

luaposix's home page is at https://github.com/luaposix/luaposix/, with documentation at https://luaposix.github.io/luaposix.

Noteworthy changes in release 36.0 (2023-01-29) [stable]

Incompatible Changes

• posix.spawn always returns integer, string whether fork fails immediately, or whatever waiting for the spawned process reports. When the second result value is "exited", the first is the exit status; for "killed" or "stopped" second value, the first is the signal number that caused it; otherwise first the errno error number, followed by the associated error string.

  The documentation for posix.spawn has always been wrong up until now, but this small change to simplify the returned results will require checking whether the second result value is "exited", "killed", "stopped" or any other string before interpreting the first result... which was also necessary in prior versions too, but now the interpretion of non-zero status by clients is less messy and somewhat compatible with the happy path of using previous releases.

• Argument type errors for posix.sys.msg.msgctl, posix.sys.resource.setrlimit, posix.sys.socket.bind, posix.sys.socket.connect, posix.sys.socket.getaddrinfo, posix.sys.socket.sendto and posix.time.nanosleep all use "integer" in full rather than "int".

Bugs Fixed

• luke no longer crashes in std.normalize require loops occasionally in Lua 5.4.

• Don't leak err into global scope from compat.open

• Correct LDoc comments for sys.resource.setrlimit.

• Where an integer argument is expected, for consistency with Lua 5.2 and older, always allow 0.0 to be accepted as if 0 had been passed. For example: pwd.getpwuid(0.0).

• require 'posix'.glob '.*' continues to invoke the backwards compatibility glob function, but that no longer prevents access to the preloaded require 'posix'.glob.glob binding.

• The fcntl binding is still available from the top-level posix module as require 'posix'.fcntl, but that no longer prevents access to the preloaded require 'posix'.fcntl.fcntl binding.

• poll.poll and poll.rpoll LDocs correctly describe the returned integer as being 0 for timeout or the number of ready file descriptors.

• stdio.fdopen returned streams can be closed from Lua 5.1 without a NULL pointer dereference crash.

• Both sys.resource.getrlimit and sys.resource.setrlimit properly roundtrip rlim_t values.

• sys.socket.getpeername and sys.socket.getsockname now return a correctly filled sockaddr table. In case of an AF_UNIX socket, the returned path is now cropped to the correct length.

• time constants are nil valued, even on hosts which fail to define them when _POSIX_TIMERS is set as if they should be.

• time.gmtime and time.localtime no longer wrap around with arguments of 2^31 and larger.

• time.gmtime and time.localtime propagate any tm_gmoffset and tm_zone fields supported by the host's struct tm.

• time.strftime reliably fills %z and %Z specifiers. Note that if your host POSIX library provides a strftime that assumes the local timezone, %z will always print the local UTC offset, regardless of the tm_gmoffset field value passed in.

  Consider (subject to host strftime implementation!):

  local t = require 'posix.time'
  local now = t.time()
  local zulu_t = t.strftime("%c UTC+0000", t.gmtime(now)))
  local localt = t.strftime("%c %Z UTC%z", t.localtime(now)))
  

• unistd.getcwd no longer leaks memory if __GNU__ was defined at compile time.

• unistd.readlink works reliably inside a /proc filesystem.

• unistd.write takes an optional third argument nbytes to conform better to the SUSv3 specification. For backwards compatibility, the entirety of buf is written when a third argument is not passed (or is nil).

• Many bindings use now a lua_Integer (with at least 53 bits for magnitude, depending on the host Lua version) instead of a C int type to pass numeric arguments, so much larger values can be successfully passed to and from the following bindings: fcntl.open, posix.fcntl.posix_fadvise, fnmatch.fnmatch, posix.grp.getgrgid, pwd.getpwuid, sched.sched_getscheduler, sched.sched_setscheduler, signal.kill, signal.killpg, signal.raise, sys.msg.msgget, sys.msg.msgrcv, sys.socket.recv, sys.socket.recvfrom, sys.socket.setsockopt, sys.stat.S_ISBLK, sys.stat.S_ISCHR, sys.stat.S_ISDIR, sys.stat.S_ISFIFO, sys.stat.S_ISLNK, sys.stat.S_ISREG, sys.stat.S_ISSOCK, sys.stat.chmod, sys.stat.mkdir, sys.stat.mkfifo, sys.stat.umask, sys.wait.wait, syslog.LOG_MASK, time.mktime, unistd._exit, unistd.alarm, unistd.ftruncate, unistd.getegid, unistd.geteguid, unistd.getgid, unistd.getopt, unistd.getpgrp, unistd.getpid, unistd.getppid, unistd.getuid, unistd.gethostid, unistd.lseek, unistd.pathconf, unistd.read, unistd.setpid, unistd.sleep, unistd.sysconf,
  unistd.truncate, utime.utime.

• Most of the spec examples run correctly on FreeBSD now!

New Features

• unistd.write takes an optional fourth argument offset to allow efficent writing of a substring of buf. For backwards compatibility, the entirety of buf is written when the third and fourth arguments are not passed (or are nil).

• When running in luajit, use luajit's internal bit functions instead of depending on the bit32 module being available.

Install it with LuaRocks, using:

luarocks install luaposix 36.0