[ANN] luaposix 36.0 released

[Gary V. Vaughan <gary@...>]

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 `wait`ing 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.