description
lunix is a bindings library module to common Unix system APIs. The module is regularly tested with Linux (glibc and musl), OS X, FreeBSD, NetBSD, OpenBSD, Solaris, and AIX. The best way to describe it is in contradistinction to luaposix, the most popular bindings module for Unix APIs in Lua.
Unlike luaposix, it strives to be as thread-safe as possible on the host platform. Interfaces like strerror_r and O_CLOEXEC are used throughout. The module even includes a novel solution for the inherently non-thread-safe umask system call, where calling umask from one thread might result in another thread creating a file with unsafe or unexpected permissions.
Unlike luaposix, the library does not restrict itself to POSIX. For example, chroot(2) and setgroups(2) are provided, which are not specified by POSIX. Where possible the library emulates an interface when not available natively. For example, the library provides arc4random (absent on Linux and Solaris), clock_gettime (absent on OS X), a thread-safe timegm (absent on Solaris and AIX), getifaddrs (absent on Solaris 10 and AIX), and sigtimedwait (absent on OS X and OpenBSD).
Unlike luaposix, the library prefers dealing with FILE handles rather than raw integer descriptors to minimize the risk of descriptor leaks. Interfaces likes chdir(2), stat(2), and opendir(3) are overloaded, accepting a string path, FILE object, DIR object, or integer file descriptor.
The module has bindings to many common Unix interfaces, including _exit, accept, access, alarm, arc4random, arc4random_buf, arc4random_stir, arc4random_uniform, bind, bitand, bitor, chdir, chmod, chown, chroot, clearerr, clock_gettime, close, closedir, closelog, compl, connect, dup, dup2, dup3, execl, execlp, execve, execvp, exit, faccessat, fchmod, fchown, fcntl, fdatasync, fdopen, fdopendir, feof, ferror, fgetc, fileno, flockfile, fnmatch, fopen, fopenat, fork, fpathconf, fstat, fstatat, fsync, ftrylockfile, funlockfile, gai_strerror, getaddrinfo, getc, getcwd, getegid, getenv, geteuid, getgid, getgrgid, getgrnam, getgroups, gethostname, getifaddrs, getmode, getnameinfo, getopt, getpeername, getpgid, getpgrp, getpid, getppid, getprogname, getpwnam, getpwuid, getrlimit, getrusage, getsockname, gettimeofday, getuid, grantpt, ioctl, isatty, issetugid, kill, LOG_MASK, LOG_UPTO, lchown, link, listen, lockf, lseek, lstat, mkdir, mkdirat, mkfifo, mkfifoat, mkpath, open, openat, opendir, openlog, pathconf, pipe, poll, posix_fadvise, posix_fallocate, posix_fopenpt, posix_openpt, pread, ptsname, pwrite, raise, read, readdir, readlink, readlinkat, realpath, recv, recvfrom, recvfromto, regcomp, regerror, regexec, regfree, rename, renameat, rewinddir, rmdir, S_ISBLK, S_ISCHR, S_ISDIR, S_ISFIFO, S_ISLNK, S_ISREG, S_ISSOCK, send, sendto, sendtofrom, setegid, setenv, seteuid, setgid, setgroups, setlocale, setlogmask, setpgid, setrlimit, setsid, setsockopt, setuid, shutdown, sigaction, sigaddset, sigdelset, sigemptyset, sigfillset, sigismember, sigprocmask, sigtimedwait, sigwait, sleep, socket, socketpair, stat, strerror, strsignal, symlink, symlinkat, sysconf, syslog, tcgetpgrp, tcgetsid, tcsetpgrp, timegm, truncate, tzset, umask, uname, unlink, unlinkat, unlockpt, unsetenv, wait, waitpid, write, and xor.
See the user guide for the full list of interfaces supported.
usage
Comprehensive usage is documented in the lunix Userguide PDF. For easy browsing use a PDF viewer with a side tab for the table of contents, such as Preview.app on OS X.
todo
Block signals in unixL_getumask.
Explore emulation of closefrom, which is available natively or trivially emulated using an fcntl call on on every platform except Linux and OS X. But we should be able to scan /proc/self/fd on Linux and /dev/fd on OS X, at least as long we're not chroot'd and have a descriptor slot to spare.
Explore longjmp or kqueue solutions to sigtimedwait emulation.
news
2023-08-07
macOS 13.0 added mkfifoat.
Unbreak getpeername and getsockname on FreeBSD and NetBSD, where the untruncated sockaddr length is returned in the .sa_len member of the passed struct sockaddr, not stored in the third, socklen_t parameter, which the kernel clamps to the provided input size.
2022-06-29
Improve regerror binding in light of the realization that regerror might not be idempotent if the locale changed.
2022-06-23
Update README.md and lunix.tex (PDF userguide) to include all exported routines, albeit without added documentation.
Tagged rel-20220623 (808cbc3fba16ec25e26ab110a8d66462444fb538).
2022-06-22
Add access and faccessat.
2022-03-31
Add getcwd and realpath.
Tagged rel-20220331 (42f49acf1f7a3fa77085cb57542c6a5d8b47cf13).
2021-09-02
Add Lua 5.4 support.
Fix bugs with struct sockaddr copying.
Remove sysctl+RANDOM_UUID usage on Linux for arc4random compat routines, fixing glibc 2.32+ builds.
Add clearerr, feof, ferror, fgetc, getc, and shutdown.
Add unix.unsafe module with bindings that accept or return raw pointer arguments, including calloc, fcntl, fmemopen, free, getsockopt, ioctl, malloc, memcpy, memset, mlock, mlockall, mmap, munlock, munlockall, munmap, realloc, reallocarray, setsockopt, strlen, and strnlen.
Tagged rel-20210902 (fd1b10eb89b0accddead24fded3d0aa1738b0c51).
2019-04-12
Add regcomp, regerror, regexec, and regfree.
2019-04-03
Add closelog, LOG_MASK, LOG_UPTO, openlog, setlogmask, and syslog.
2017-05-11
Add mkdirat, mkfifoat, openat, renameat, and unlinkat.
Tagged rel-20170511 (03f8e0cde8fbe149b914e322fab9b1535b115677).
2016-10-26
Many new interfaces since the last news update. See the userguide. Most recently many socket interfaces, plus recvfromto() and sendtofrom(), de facto interfaces reimplemented in various open source projects for sending and receiving UDP packets on wildcard addresses.
Tagged rel-20161026 (977c3f839c4c29fcb4ec52d966a1eba787d30468).
2015-03-13
Add fstat, stat, and lstat.
Add getgroups, and setgroups.
Add getaddrinfo and gai_strerror.
Add sigaction.
Add dup2, and fileno.
Fix build for uclibc and musl libc.
Add autoconf feature detection (optional) (incomplete).
2014-08-19
Add alternative, optional clock_gettime implementation on OS X which uses the Mach clock_get_time API. This is mostly for documentation purposes. mach_absolute_time is definitely monotonic on x86, even across cores and CPU packages, notwithstanding use of the CPU TSC. (All the cargo-culting about RDTSC SMP issues become outdated nearly a decade ago.) PPC also seems to have been properly monotonic. I would be surprised if the mach_absolute_time implementation on ARM isn't invariant, although at the time of writing I'm still trying to confirm with Apple engineers. (Update: ARMv7 and ARMv8 system counter is invariant, so if mach_absolute_time uses CNTPCT or CNTVCT it's SMP-safe.)
Fix dh_lua Debian build by linking in -lrt.
Add debian-distclean target. dh_lua on Ubuntu 12.04 chokes on intermediate files generated by prior runs. debian-distclean uses `git ls-files --others debian/` to remove these.
Tag rel-20140819 (41a768314a72660405440cc3105472de86dfbf3d).
2014-08-04
Add gethostname, lchown, pread, pwrite, read, write.
2014-08-01
Add fcntl, flockfile, ftrylockfile, funlockfile, and getppid.
Fix strerror_r usage on Linux/glibc
2014-08-01
Fix sigtimedwait emulation on OS X and OpenBSD.
Tag rel-20140801 (46491507866b2fcf1f9e9f73616580676b56d4eb).
2014-07-31
Add strsignal, sigset_t, sigemptyset, sigfillset, sigaddset, sigdelset, sigismember, sigprocmask, sigtimedwait, kill, and raise. sigtimedwait is emulated on OS X and OpenBSD.
Fix usage of strerror_r on Linux/glibc.
Tag rel-20140731 (ff7afdc88ad4a68c5dd1cfd96162cb9a1cf7d749).
2014-07-27
Add errno mappings.
2014-07-26
Add fork, execve, execl, execlp, execvp, _exit, exit, and waitpid bindings.
Add __ipairs metamethod to environ table.
2014-07-25
Add getenv, setenv, and unsetenv bindings.
Add environ table which proxies the process-global environ array using __index, __newindex, and __pairs metamethods.
2014-07-24
Add prefixlen member to getifaddrs tables.
Refactor examples/getifaddrs.lua to behave more like ifconfig(1).
Add CLOCK_MONOTONIC and CLOCK_REALTIME constants.
2014-07-24
Add getifaddrs binding, and emulate when not available. Emulation was tested on all supported systems (Linux, *BSD, OS X, Solaris, and AIX), although AIX was the only system that didn't actually have getifaddrs. There are four separate implementations: KAME SIOCGIFADDR_IN6, KAME SIOCGLIFADDR, AIX SIOCGIFADDR6, and Solaris SIOCGLIFADDR. But all four utilize SIOCGIFCONF to derive the interface list, so IPv6 is not supported where the SIOCGIFCONF implementation cannot return sockaddr_in6 structures. (AIX and most KAME-derived network stacks return variable-sized ifreq structures. NetBSD has padded out their ifreq structure to hold IPv6 addresses in fixed space. Solaris 11 and Linux cannot return IPv6 addresses in ifreq, but they both support getifaddrs natively so emulation isn't used by default. Only Solaris 10 is IPv4-only at the moment.)
Begin process of adding constants to the module, starting with socket address families (AF_INET, etc) and interface flags (IFF_BROADCAST, etc).
Tag rel-20140724 (d8b6a95224021f2dd2bfb54d972c567b9984a318).
2014-07-22
Use getauxval(AT_SECURE) on Linux to emulate issetugid when available.
2014-07-17
Fix readdir_r usage on AIX. AIX returns EBADF on end-of-directory.
2014-04-19
Simplify and make more robust arc4random stirring.
Add issetugid binding.
Tag rel-20140419 (73629b44af998aa2f5c3f79793485ddd2c941370).
2014-03-31
Add opendir, readdir, rewinddir, and closedir. opendir returns an object with the methods :read (same as readdir), :rewind (same as rewinddir), :close (same as closedir), and :files (an iterator over readdir).
Tag rel-20140331 (8a83e917cb460319c080351fb90c8def0b21e488).
2014-03-23
Fix behavior of arc4random_uniform.
Add tzset binding.
Add 5.3 build support.
Add documentation as user guide PDF.
Tag rel-20140323 (3bb1f504608af44783098b18e02f93db4d7fbd96).
2014-01-28
Published.
license
Copyright (c) 2014-2017, 2019-2022 William Ahern
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
source
git clone https://25thandClement.com/~william/projects/lunix.git