From be13c2e8845423cec17af429fc4e16a5d9749e47 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 26 Oct 2025 10:54:58 -0700 Subject: Replace nng_pipe_get_addr, nng_stream_get_addr, and the NNG_OPT_REMADDR option. More direct access methods are provided instead. This results in much lower friction when using, and is a step on the path to removing NNG_OPT_LOCADDR as well. We need to figure a solution for NNG_OPT_LOCADDR for dialers; for listeners there is little use in it either, and it will be removed. (Dialers will probably get a new NNG_OPT_BIND_IP option.) --- docs/ref/api/pipe.md | 12 ++++++++++-- docs/ref/api/stream.md | 5 ----- docs/ref/migrate/nng1.md | 28 ++++++++++++++++++++++++++++ docs/ref/tran/ipc.md | 29 ++++++++++++++--------------- docs/ref/xref.md | 6 ++---- 5 files changed, 54 insertions(+), 26 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/api/pipe.md b/docs/ref/api/pipe.md index 4fae1d06..97540908 100644 --- a/docs/ref/api/pipe.md +++ b/docs/ref/api/pipe.md @@ -84,6 +84,16 @@ either [`nng_dialer_id`] or [`nng_listener_id`] for the returned object will ret > The socket, or the endpoint, returned by these functions may be in the process of closing, > and might not be further usable as a result. (Other functions will result in [`NNG_ECLOSED`].) +## Pipe Socket Addresses + +```c +nng_err nng_pipe_peer_addr(nng_pipe p, nng_sockaddr *sap); +nng_err nng_pipe_self_addr(nng_pipe p, nng_sockaddr *sap); +``` + +The [`nng_sockaddr`] for the local (self) or remote (peer) of the pipe is available using these +functions. The associated address will be stored in the location pointed to by _sap_. + ## Pipe Options ```c @@ -91,7 +101,6 @@ nng_err nng_pipe_get_bool(nng_pipe p, const char *opt, bool *valp); nng_err nng_pipe_get_int(nng_pipe p, const char *opt, int *valp); nng_err nng_pipe_get_ms(nng_pipe p, const char *opt, nng_duration *valp); nng_err nng_pipe_get_size(nng_pipe p, const char *opt, size_t *valp); -nng_err nng_pipe_get_addr(nng_pipe p, const char *opt, nng_sockaddr *valp); nng_err nng_pipe_get_string(nng_pipe p, const char *opt, const char **valp); nng_err nng_pipe_get_strcpy(nng_pipe p, const char *opt, char *val, size_t len); nng_err nng_pipe_get_strdup(nng_pipe p, const char *opt, char **valp); @@ -102,7 +111,6 @@ nng_err nng_pipe_get_strlen(nng_pipe p, const char *opt, size_t *lenp); {{hi:`nng_pipe_get_int`}} {{hi:`nng_pipe_get_ms`}} {{hi:`nng_pipe_get_size`}} -{{hi:`nng_pipe_get_addr`}} {{hi:`nng_pipe_get_string`}} {{hi:`nng_pipe_get_strcpy`}} {{hi:`nng_pipe_get_strdup`}} diff --git a/docs/ref/api/stream.md b/docs/ref/api/stream.md index a2f29238..3bed7923 100644 --- a/docs/ref/api/stream.md +++ b/docs/ref/api/stream.md @@ -103,7 +103,6 @@ nng_err nng_stream_get_string(nng_stream *s, const char *opt, const char **valp) {{hi:`nng_stream_get_int`}} {{hi:`nng_stream_get_ms`}} {{hi:`nng_stream_get_size`}} -{{hi:`nng_stream_get_addr`}} {{hi:`nng_stream_get_string`}} These functions are used to obtain value of an option named _opt_ from the stream _s_, and store it in the location referenced by _valp_. @@ -114,10 +113,6 @@ are available, and which type they may be accessed using. In the case of `nng_stream_get_string`, the string pointer is only guaranteed to be valid while the stream exists. Callers should make a copy of the data if required before closing the stream. -> [!NOTE]: -> The `nng_stream_get_addr` function is deprecated and will be removed. Use the -> [`nng_stream_peer_addr`] or [`nng_stream_self_addr`] functions instead. - ## Stream Factories ```c diff --git a/docs/ref/migrate/nng1.md b/docs/ref/migrate/nng1.md index 52b786cc..6e0a1143 100644 --- a/docs/ref/migrate/nng1.md +++ b/docs/ref/migrate/nng1.md @@ -173,6 +173,13 @@ address separated by a semicolon. This was provided for legacy libnanomsg compatibility, and is no longer offered. The correct way to specify a local address is by setting `NNG_OPT_LOCADDR` on the dialer. +## Support for Remote Address Options Removed + +The `NNG_OPT_REMADDR` option is removed. For streams and pipes, there are +[`nng_stream_peer_addr`] and [`nng_pipe_peer_addr`] functions. For dialers +and stream dialers, the application should track the relevant information +used to configure the listener. + ## IPC Option Type Changes The types of [`NNG_OPT_PEER_GID`], [`NNG_OPT_PEER_PID`], [`NNG_OPT_PEER_UID`], and [`NNG_OPT_PEER_ZONEID`] @@ -247,6 +254,9 @@ such as one ending in a suffix like `_bool` (to access a `bool` typed option). ## Stream Options +The `nng_stream_get_addr` function is removed. +Use the new [`nng_stream_peer_addr`] or [`nng_stream_peer_self_addr`] instead. + The ability to set options on streams after they have been created is no longer present. (It turns out that this was not very useful.) All functions `nng_stream_set_xxx` are removed. For tuning the `NNG_OPT_TCP_NODELAY` or similar properties, set the option on the listener @@ -277,6 +287,10 @@ before bringing them into the socket itself. The `NNG_OPT_TCP_BOUND_PORT` port is renamed to just [`NNG_OPT_BOUND_PORT`], and is available for listeners using transports based on either TCP or UDP. +The `nng_pipe_get_addr` function has been removed, and replaced with the new +[`nng_pipe_peer_addr`] and [`nng_pipe_self_addr`] functions. These should be +easier to use. + ## Socket Options The `NNG_OPT_PROTO`, `NNG_OPT_PROTONAME`, `NNG_OPT_PEER`, and `NNG_OPT_PEERNAME` options @@ -401,4 +415,18 @@ The Layer 2 special ZeroTier transport has been removed. It is possible to use NNG with ZeroTier using TCP/IP, and a future update is planned to provided coexistence between ZeroTier & the native stack's TCP/IP using lwIP. +## Abstract Autobinding No Longer Supported + +As we have removed `NNG_OPT_LOCADDR` for listeners, it is no longer possible to meaningfully +use autobinding with abstract sockets on Linux. This is trivially worked around by using a +large (say 128-bit) random integer as the name. + +This can be done via using of [`nng_random`] combined with `sprintf`, as the following example demonstrates: + +```c +char url[256]; +snprintf(url, sizeof (url), `abstract://my-app-%08x-%08x-%08x-%08x", + nni_random(), nni_random(), nni_random(), nni_random()); +``` + {{#include ../xref.md}} diff --git a/docs/ref/tran/ipc.md b/docs/ref/tran/ipc.md index 3d046ee5..e5838d11 100644 --- a/docs/ref/tran/ipc.md +++ b/docs/ref/tran/ipc.md @@ -24,7 +24,7 @@ name in the file system where the socket or named pipe should be created. > [!NOTE] > When using relative paths on POSIX systems, the address used and returned -> in properties like [`NNG_OPT_LOCADDR`] will also be relative. +> in functions such as [`nng_pipe_peer_addr`] will also be relative. > Consequently, they will only be interpreted the same by processes that have > the same working directory. > To ensure maximum portability and safety, absolute paths are recommended @@ -50,10 +50,11 @@ Abstract sockets use a URI-encoded name after the {{i:`abstract://`}} scheme, wh in the path, including embedded `NUL` bytes. For example, the name `"a\0b"` would be represented as `abstract://a%00b`. -> [!TIP] -> An empty name may be used with a listener to request "auto bind" be used to select a name. -> In this case the system will allocate a free name. -> The name assigned may be retrieved using [`NNG_OPT_LOCADDR`]. +> [!NOTE] +> _NNG_ no longer supports "auto binding" where the kernel allocates a random unused name. +> A simple solution to this is to allocate a large random number, such as a random UUID +> or a concatenation of four random values from [`nng_random`]. The chance of a collision +> can be made arbitrarily small by appending additional random values. Abstract names do not include the leading `NUL` byte used in the low-level socket address. @@ -76,16 +77,14 @@ except for abstract sockets, which use [`nng_sockaddr_abstract`]. The following transport options are supported by this transport, where supported by the underlying platform. -| Option | Type | Description | -| ------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ | -| `NNG_OPT_IPC_PERMISSIONS` | `int` | Settable on listeners before they start, this is the UNIX file mode used when creating the socket. | -| `NNG_OPT_LOCADDR` | [`nng_sockaddr`] | Local socket address, either [`nng_sockaddr_ipc`] or [`nng_sockaddr_abstract`]. | -| `NNG_OPT_REMADDR` | [`nng_sockaddr`] | Remote socket address, either [`nng_sockaddr_ipc`] or [`nng_sockaddr_abstract`]. | -| `NNG_OPT_PEER_GID` | `int` | Read only option, returns the group ID of the process at the other end of the socket, if platform supports it. | -| `NNG_OPT_PEER_PID` | `int` | Read only option, returns the processed ID of the process at the other end of the socket, if platform supports it. | -| `NNG_OPT_PEER_UID` | `int` | Read only option, returns the user ID of the process at the other end of the socket, if platform supports it. | -| `NNG_OPT_PEER_ZONEID` | `int` | Read only option, returns the zone ID of the process at the other end of the socket, if platform supports it. | -| [`NNG_OPT_LISTEN_FD`] | `int` | Write only for listeners before they start, use the named socket for accepting (for use with socket activation). | +| Option | Type | Description | +| ------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------ | +| `NNG_OPT_IPC_PERMISSIONS` | `int` | Settable on listeners before they start, this is the UNIX file mode used when creating the socket. | +| `NNG_OPT_PEER_GID` | `int` | Read only option, returns the group ID of the process at the other end of the socket, if platform supports it. | +| `NNG_OPT_PEER_PID` | `int` | Read only option, returns the processed ID of the process at the other end of the socket, if platform supports it. | +| `NNG_OPT_PEER_UID` | `int` | Read only option, returns the user ID of the process at the other end of the socket, if platform supports it. | +| `NNG_OPT_PEER_ZONEID` | `int` | Read only option, returns the zone ID of the process at the other end of the socket, if platform supports it. | +| [`NNG_OPT_LISTEN_FD`] | `int` | Write only for listeners before they start, use the named socket for accepting (for use with socket activation). | ### Other Configuration Parameters diff --git a/docs/ref/xref.md b/docs/ref/xref.md index d64840cb..80a3d1b7 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -125,7 +125,6 @@ [`nng_stream_get_int`]: ../api/stream.md#getting-stream-options [`nng_stream_get_ms`]: ../api/stream.md#getting-stream-options [`nng_stream_get_size`]: ../api/stream.md#getting-stream-options -[`nng_stream_get_addr`]: ../api/stream.md#getting-stream-options [`nng_stream_get_string`]: ../api/stream.md#getting-stream-options [`nng_stream_dialer`]: ../api/stream.md#stream-factories [`nng_stream_listener`]: ../api/stream.md#stream-factories @@ -162,7 +161,6 @@ [`nng_stream_listener_get_int`]: ../api/stream.md#stream-factory-options [`nng_stream_listener_get_ms`]: ../api/stream.md#stream-factory-options [`nng_stream_listener_get_size`]: ../api/stream.md#stream-factory-options -[`nng_stream_listener_get_addr`]: ../api/stream.md#stream-factory-options [`nng_stream_listener_get_string`]: ../api/stream.md#stream-factory-options [`nng_stream_listener_set_bool`]: ../api/stream.md#stream-factory-options [`nng_stream_listener_set_int`]: ../api/stream.md#stream-factory-options @@ -257,9 +255,10 @@ [`nng_pipe_get_int`]: ../api/pipe.md#pipe-options [`nng_pipe_get_ms`]: ../api/pipe.md#pipe-options [`nng_pipe_get_size`]: ../api/pipe.md#pipe-options -[`nng_pipe_get_addr`]: ../api/pipe.md#pipe-options [`nng_pipe_get_string`]: ../api/pipe.md#pipe-options [`nng_pipe_notify`]: ../api/pipe.md#pipe-notifications +[`nng_pipe_peer_addr`]: ../api/pipe.md#pipe-socket-addresses +[`nng_pipe_self_addr`]: ../api/pipe.md#pipe-socket-addresses [`nng_sockaddr`]: ../TODO.md [`nng_sockaddr_in`]: ../TODO.md [`nng_sockaddr_in6`]: ../TODO.md @@ -451,7 +450,6 @@ [`NNG_OPT_RECVBUF`]: ../api/sock.md#NNG_OPT_RECVBUF [`NNG_OPT_RECVMAXSZ`]: ../api/sock.md#NNG_OPT_RECVMAXSZ [`NNG_OPT_LOCADDR`]: ../api/sock.md#NNG_OPT_LOCADDR -[`NNG_OPT_REMADDR`]: ../api/sock.md#NNG_OPT_REMADDR [`NNG_OPT_PEER_UID`]: ../tran/ipc.md#NNG_OPT_PEER_UID [`NNG_OPT_PEER_GID`]: ../tran/ipc.md#NNG_OPT_PEER_GID [`NNG_OPT_PEER_PID`]: ../tran/ipc.md#NNG_OPT_PEER_PID -- cgit v1.2.3-70-g09d2