From 55c8cb9b7acd351d8f145194c6e76a10f10b2f33 Mon Sep 17 00:00:00 2001 From: Sinister Rectus Date: Wed, 24 Jul 2024 19:50:07 -0400 Subject: [PATCH] Clean up and expand docs for constants/options --- docs.md | 199 ++++++++++++++++++++++++++++++++++++------------ src/constants.c | 2 + 2 files changed, 154 insertions(+), 47 deletions(-) diff --git a/docs.md b/docs.md index 85c670dc..47b17768 100644 --- a/docs.md +++ b/docs.md @@ -82,6 +82,7 @@ within the context of luv's Lua API. Low-level implementation details and unexposed C functions and types are not documented here except for when they are relevant to behavior seen in the Lua module. +- [Constants][] - [Error handling][] - [Version checking][] - [`uv_loop_t`][] — Event loop @@ -109,14 +110,109 @@ are relevant to behavior seen in the Lua module. - [Miscellaneous utilities][] - [Metrics operations][] +## Constants + +[constants]: #constants + +As a Lua library, luv supports and encourages the use of lowercase strings to +represent options. For example: +```lua +-- signal start with string input +uv.signal_start("sigterm", function(signame) + print(signame) -- string output: "sigterm" +end) +``` + +However, luv also superficially exposes libuv constants in a Lua table at +`uv.constants` where its keys are uppercase constant names and their associated +values are integers defined internally by libuv. The values from this table may +be supported as function arguments, but their use may not change the output +type. For example: + +```lua +-- signal start with integer input +uv.signal_start(uv.constants.SIGTERM, function(signame) + print(signame) -- string output: "sigterm" +end) +``` + +The uppercase constants defined in `uv.constants` that have associated +lowercase option strings are listed below. + +### Address Families + +- `AF_UNIX`: "unix" +- `AF_INET`: "inet" +- `AF_INET6`: "inet6" +- `AF_IPX`: "ipx" +- `AF_NETLINK`: "netlink" +- `AF_X25`: "x25" +- `AF_AX25`: "as25" +- `AF_ATMPVC`: "atmpvc" +- `AF_APPLETALK`: "appletalk" +- `AF_PACKET`: "packet" + +### Signals + +- `SIGHUP`: "sighup" +- `SIGINT`: "sigint" +- `SIGQUIT`: "sigquit" +- `SIGILL`: "sigill" +- `SIGTRAP`: "sigtrap" +- `SIGABRT`: "sigabrt" +- `SIGIOT`: "sigiot" +- `SIGBUS`: "sigbus" +- `SIGFPE`: "sigfpe" +- `SIGKILL`: "sigkill" +- `SIGUSR1`: "sigusr1" +- `SIGSEGV`: "sigsegv" +- `SIGUSR2`: "sigusr2" +- `SIGPIPE`: "sigpipe" +- `SIGALRM`: "sigalrm" +- `SIGTERM`: "sigterm" +- `SIGCHLD`: "sigchld" +- `SIGSTKFLT`: "sigstkflt" +- `SIGCONT`: "sigcont" +- `SIGSTOP`: "sigstop" +- `SIGTSTP`: "sigtstp" +- `SIGBREAK`: "sigbreak" +- `SIGTTIN`: "sigttin" +- `SIGTTOU`: "sigttou" +- `SIGURG`: "sigurg" +- `SIGXCPU`: "sigxcpu" +- `SIGXFSZ`: "sigxfsz" +- `SIGVTALRM`: "sigvtalrm" +- `SIGPROF`: "sigprof" +- `SIGWINCH`: "sigwinch" +- `SIGIO`: "sigio" +- `SIGPOLL`: "sigpoll" +- `SIGLOST`: "siglost" +- `SIGPWR`: "sigpwr" +- `SIGSYS`: "sigsys" + +### Socket Types + +- `SOCK_STREAM`: "stream" +- `SOCK_DGRAM`: "dgram" +- `SOCK_SEQPACKET`: "seqpacket" +- `SOCK_RAW`: "raw" +- `SOCK_RDM`: "rdm" + +### TTY Modes + +- `TTY_MODE_NORMAL`: "normal" +- `TTY_MODE_RAW`: "raw" +- `TTY_MODE_IO`: "io" + ## Error Handling [Error handling]: #error-handling -In libuv, errors are negative numbered constants; however, while those errors are exposed through `uv.errno`, -the functions used to handle them are not exposed to luv users. Instead, if an -internal error is encountered, the luv function will return to the caller an -assertable `nil, err, name` tuple. +In libuv, errors are represented by negative numbered constants. While these +constants are made available in the `uv.errno` table, they are not returned by +luv funtions and the libuv functions used to handle them are not exposed. +Instead, if an internal error is encountered, the failing luv function will +return to the caller an assertable `nil, err, name` tuple: - `nil` idiomatically indicates failure - `err` is a string with the format `{name}: {message}` @@ -130,10 +226,8 @@ When a function is called successfully, it will return either a value that is relevant to the operation of the function, or the integer `0` to indicate success, or sometimes nothing at all. These cases are documented below. -### `uv.errno` - -A table value which exposes error constants as a map, where the key is the error name (without the `UV_` prefix) and its value is a negative number. -See Libuv's [Error constants](https://docs.libuv.org/en/v1.x/errors.html#error-constants) page for further details. +Below is a list of known error names and error strings. See libuv's +[error constants][] page for an original source. - `E2BIG`: argument list too long. - `EACCES`: permission denied. @@ -1094,8 +1188,8 @@ Reception of some signals is emulated on Windows: -- Create a new signal handler local signal = uv.new_signal() -- Define a handler function -uv.signal_start(signal, "sigint", function(signal) - print("got " .. signal .. ", shutting down") +uv.signal_start(signal, "sigint", function(signame) + print("got " .. signame .. ", shutting down") os.exit(1) end) ``` @@ -1107,32 +1201,36 @@ it. **Returns:** `uv_signal_t userdata` or `fail` -### `uv.signal_start(signal, signum, callback)` +### `uv.signal_start(signal, signame, callback)` -> method form `signal:start(signum, callback)` +> method form `signal:start(signame, callback)` **Parameters:** - `signal`: `uv_signal_t userdata` -- `signum`: `integer` or `string` +- `signame`: `string` or `integer` - `callback`: `callable` - - `signum`: `string` + - `signame`: `string` Start the handle with the given callback, watching for the given signal. +See [Constants][] for supported `signame` input and output values. + **Returns:** `0` or `fail` -### `uv.signal_start_oneshot(signal, signum, callback)` +### `uv.signal_start_oneshot(signal, signame, callback)` -> method form `signal:start_oneshot(signum, callback)` +> method form `signal:start_oneshot(signame, callback)` **Parameters:** - `signal`: `uv_signal_t userdata` -- `signum`: `integer` or `string` +- `signame`: `string` or `integer` - `callback`: `callable` - - `signum`: `string` + - `signame`: `string` Same functionality as `uv.signal_start()` but the signal handler is reset the moment the signal is received. +See [Constants][] for supported `signame` input and output values. + **Returns:** `0` or `fail` ### `uv.signal_stop(signal)` @@ -1274,28 +1372,32 @@ When the child process exits, `on_exit` is called with an exit code and signal. **Returns:** `uv_process_t userdata`, `integer` -### `uv.process_kill(process, signum)` +### `uv.process_kill(process, signame)` -> method form `process:kill(signum)` +> method form `process:kill(signame)` **Parameters:** - `process`: `uv_process_t userdata` -- `signum`: `integer` or `string` or `nil` (default: `sigterm`) +- `signame`: `string` or `integer` or `nil` (default: `sigterm`) Sends the specified signal to the given process handle. Check the documentation on `uv_signal_t` for signal support, specially on Windows. +See [Constants][] for supported `signame` input values. + **Returns:** `0` or `fail` -### `uv.kill(pid, signum)` +### `uv.kill(pid, signame)` **Parameters:** - `pid`: `integer` -- `signum`: `integer` or `string` or `nil` (default: `sigterm`) +- `signame`: `string` or `integer` or `nil` (default: `sigterm`) Sends the specified signal to the given PID. Check the documentation on `uv_signal_t` for signal support, specially on Windows. +See [Constants][] for supported `signame` input values. + **Returns:** `0` or `fail` ### `uv.process_get_pid(process)` @@ -1549,11 +1651,12 @@ TCP handles are used to represent both TCP streams and servers. ### `uv.new_tcp([flags])` **Parameters:** -- `flags`: `string` or `nil` +- `flags`: `string` or `integer` or `nil` Creates and initializes a new `uv_tcp_t`. Returns the Lua userdata wrapping it. -Flags may be a family string: `"unix"`, `"inet"`, `"inet6"`, `"ipx"`, -`"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, or `"packet"`. + +If set, `flags` must be a valid address family. See [Constants][] for supported +address family input values. **Returns:** `uv_tcp_t userdata` or `fail` @@ -1649,6 +1752,8 @@ later using `uv.tcp_getsockname()`. Get the address of the peer connected to the handle. +See [Constants][] for supported address `family` output values. + **Returns:** `table` or `fail` - `ip` : `string` - `family` : `string` @@ -1663,6 +1768,8 @@ Get the address of the peer connected to the handle. Get the current address to which the handle is bound. +See [Constants][] for supported address `family` output values. + **Returns:** `table` or `fail` - `ip` : `string` - `family` : `string` @@ -1723,8 +1830,7 @@ and `uv.tcp_close_reset()` calls is not allowed. Create a pair of connected sockets with the specified properties. The resulting handles can be passed to `uv.tcp_open`, used with `uv.spawn`, or for any other purpose. -When specified as a string, `socktype` must be one of `"stream"`, `"dgram"`, `"raw"`, -`"rdm"`, or `"seqpacket"`. +See [Constants][] for supported `socktype` input values. When `protocol` is set to 0 or nil, it will be automatically chosen based on the socket's domain and type. When `protocol` is specified as a string, it will be looked up using the `getprotobyname(3)` function (examples: `"ip"`, `"icmp"`, `"tcp"`, `"udp"`, etc). @@ -2059,16 +2165,11 @@ This function is not thread safe on systems that don’t support ioctl TIOCGPTN **Parameters:** - `tty`: `uv_tty_t userdata` -- `mode`: `integer` +- `mode`: `string` or `integer` Set the TTY using the specified terminal mode. -Parameter `mode` is a C enum with the following values: - - - 0 - UV_TTY_MODE_NORMAL: Initial/normal terminal mode - - 1 - UV_TTY_MODE_RAW: Raw input mode (On Windows, ENABLE_WINDOW_INPUT is - also enabled) - - 2 - UV_TTY_MODE_IO: Binary-safe I/O mode for IPC (Unix-only) +See [Constants][] for supported TTY mode input values. **Returns:** `0` or `fail` @@ -2135,9 +2236,7 @@ UDP handles encapsulate UDP communication for both clients and servers. Creates and initializes a new `uv_udp_t`. Returns the Lua userdata wrapping it. The actual socket is created lazily. -When specified, `family` must be one of `"unix"`, `"inet"`, `"inet6"`, -`"ipx"`, `"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, or -`"packet"`. +See [Constants][] for supported address `family` input values. When specified, `mmsgs` determines the number of messages able to be received at one time via `recvmmsg(2)` (the allocated buffer will be sized to be able @@ -2386,6 +2485,8 @@ Prepare for receiving data. If the socket has not previously been bound with `uv.udp_bind()` it is bound to `0.0.0.0` (the "all interfaces" IPv4 address) and a random port number. +See [Constants][] for supported address `family` output values. + **Returns:** `0` or `fail` ### `uv.udp_recv_stop(udp)` @@ -3270,12 +3371,14 @@ called in the main loop thread. Equivalent to `getaddrinfo(3)`. Either `node` or `service` may be `nil` but not both. -Valid hint strings for the keys that take a string: -- `family`: `"unix"`, `"inet"`, `"inet6"`, `"ipx"`, -`"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, or `"packet"` -- `socktype`: `"stream"`, `"dgram"`, `"raw"`, -`"rdm"`, or `"seqpacket"` -- `protocol`: will be looked up using the `getprotobyname(3)` function (examples: `"ip"`, `"icmp"`, `"tcp"`, `"udp"`, etc) +See [Constants][] for supported address `family` input and output values. + +See [Constants][] for supported `socktype` input and output values. + +When `protocol` is set to 0 or nil, it will be automatically chosen based on the +socket's domain and type. When `protocol` is specified as a string, it will be +looked up using the `getprotobyname(3)` function. Examples: `"ip"`, `"icmp"`, +`"tcp"`, `"udp"`, etc. **Returns (sync version):** `table` or `fail` - `[1, 2, 3, ..., n]` : `table` @@ -3302,8 +3405,7 @@ Valid hint strings for the keys that take a string: Equivalent to `getnameinfo(3)`. -When specified, `family` must be one of `"unix"`, `"inet"`, `"inet6"`, `"ipx"`, -`"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, or `"packet"`. +See [Constants][] for supported address `family` input values. **Returns (sync version):** `string, string` or `fail` @@ -3413,7 +3515,7 @@ the number to correspond with the table keys used in `uv.thread_getaffinity` and **Parameters:** - `thread`: `luv_thread_t userdata` -- `priority`: ``number` +- `priority`: `number` Sets the specified thread's scheduling priority setting. It requires elevated privilege to set specific priorities on some platforms. @@ -3731,6 +3833,8 @@ table. Each table key is the name of the interface while each associated value is an array of address information where fields are `ip`, `family`, `netmask`, `internal`, and `mac`. +See [Constants][] for supported address `family` output values. + **Returns:** `table` - `[name(s)]` : `table` - `ip` : `string` @@ -3954,3 +4058,4 @@ metrics counters. [libuv]: https://github.com/libuv/libuv [libuv documentation page]: http://docs.libuv.org/ [libuv API documentation]: http://docs.libuv.org/en/v1.x/api.html +[error constants]: https://docs.libuv.org/en/v1.x/errors.html#error-constants diff --git a/src/constants.c b/src/constants.c index 7549aace..b2e43fd1 100644 --- a/src/constants.c +++ b/src/constants.c @@ -321,6 +321,8 @@ static int luv_constants(lua_State* L) { lua_pushinteger(L, SIGSYS); lua_setfield(L, -2, "SIGSYS"); #endif + + // Other #if LUV_UV_VERSION_GEQ(1, 40, 0) lua_pushinteger(L, UV_UDP_MMSG_FREE); lua_setfield(L, -2, "UDP_MMSG_FREE");