From 6274913455be87cbe598b5d0534e1e80972c8efd Mon Sep 17 00:00:00 2001 From: gdamore Date: Tue, 28 Oct 2025 05:39:18 +0000 Subject: deploy: 1d69c8f0393337d4f222cc1af1af813d77922c84 --- ref/print.html | 240 ++++++++++++++++++++++++++++++--------------------------- 1 file changed, 127 insertions(+), 113 deletions(-) (limited to 'ref/print.html') diff --git a/ref/print.html b/ref/print.html index 28dc10ee..02515d48 100644 --- a/ref/print.html +++ b/ref/print.html @@ -2095,12 +2095,17 @@ either [nng_dialer_id] or [nng_listener_id] for the re

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

+
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

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);
@@ -2113,7 +2118,6 @@ nng_err nng_pipe_get_strlen(nng_pipe p, const char *opt, size_t *lenp);
 
 
 
-
 These functions are used to obtain value of an option named opt from the pipe p, and store it in the location
 referenced by valp.

 
These functions access an option as a specific type. The transport layer will have details about which options
@@ -2138,7 +2142,7 @@ typedef void (*nng_pipe_cb)(nng_pipe, nng_pipe_ev, void *);
 
 nng_err nng_pipe_notify(nng_socket s, nng_pipe_ev ev, nng_pipe_cb cb, void *arg);
-

The nng_pipe_notify function registers the callback function cb +

The nng_pipe_notify function registers the callback function cb to be called whenever the pipe event specified by ev occurs on the socket s. The callback cb will be passed arg as its final argument.

@@ -2147,9 +2151,9 @@ Each event may have at most one callback registered. Registering a callback implicitly unregisters any previously registered.

The following pipe events are supported:

- - - + + +
EventDescription
NNG_PIPE_EV_ADD_PREThis event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using nng_pipe_close) at this point, the socket will never see the pipe, and no further events will occur for the given pipe.
NNG_PIPE_EV_ADD_POSTThis event occurs after the pipe is fully added to the socket. Prior to this time, it is not possible to communicate over the pipe with the socket.
NNG_PIPE_EV_REM_POSTThis event occurs after the pipe has been removed from the socket. The underlying transport may be closed at this point, and it is not possible communicate using this pipe.
NNG_PIPE_EV_ADD_PREThis event occurs after a connection and negotiation has completed, but before the pipe is added to the socket. If the pipe is closed (using nng_pipe_close) at this point, the socket will never see the pipe, and no further events will occur for the given pipe.
NNG_PIPE_EV_ADD_POSTThis event occurs after the pipe is fully added to the socket. Prior to this time, it is not possible to communicate over the pipe with the socket.
NNG_PIPE_EV_REM_POSTThis event occurs after the pipe has been removed from the socket. The underlying transport may be closed at this point, and it is not possible communicate using this pipe.

@@ -4252,41 +4256,35 @@ nng_err nng_stream_get_string(nng_stream *s, const char *opt, const char **valp) - 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.

These functions access an option as a specific type. The transport layer will have details about which options 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

typedef struct nng_stream_dialer nng_stream_dialer;
 typedef struct nng_stream_listener nng_stream_listener;
-

-The nng_stream_listener object and nng_stream_listener objects can be thought of as factories that +

+The nng_stream_listener object and nng_stream_listener objects can be thought of as factories that create nng_stream streams.

The nng_stream_listener object a handle to a listener, which creates streams by accepting incoming connection requests. -In a BSD socket implementation, this is the entity responsible for doing bind, listen and accept. +In a BSD socket implementation, this is the entity responsible for doing bind, listen and accept. Normally a listener may be used to accept multiple, possibly many, concurrent connections.

The nng_stream_dialer object is a handle to a dialer, which creates streams by making outgoing connection requests. While there isn’t a specific BSD socket analogue, this can be thought of as a factory for TCP sockets -created by opening them with socket and then calling connect on them.

+created by opening them with socket and then calling connect on them.

Creating a Stream Factory

nng_err nng_stream_dialer_alloc(nng_stream_dialer **dialerp, const char *url);
 nng_err nng_stream_dialer_alloc_url(nng_stream_dialer **dialerp, const nng_url *url);
 nng_err nng_stream_listener_alloc(nng_stream_listener **lstenerp, const char *url);
 nng_err nng_stream_listener_alloc_url(nng_stream_listener **listenerp, const nng_url *url);
-

The nng_stream_dialer_alloc and nng_stream_dialer_alloc_url functions create a stream dialer, associated the -URL specified by url represented as a string, or as an nng_url object, respectively. The dialer is returned in the location +

The nng_stream_dialer_alloc and nng_stream_dialer_alloc_url functions create a stream dialer, associated the +URL specified by url represented as a string, or as an nng_url object, respectively. The dialer is returned in the location dialerp references.

-

The nng_stream_listener_alloc and nng_stream_listener_alloc_url functions create a stream listener, associated the +

The nng_stream_listener_alloc and nng_stream_listener_alloc_url functions create a stream listener, associated the URL specified by url represented as a string, or as an nng_url object, respectively. The listener is returned in the location listenerp references.

Example 1: Creating a TCP Listener

@@ -4302,14 +4300,14 @@ void nng_stream_listener_close(nng_stream_listener *listener); void nng_stream_listener_stop(nng_stream_listener *listener); void nng_stream_listener_free(nng_stream_listener *listener); -

The nng_stream_dialer_close and nng_stream_listener_close functions close the stream dialer or listener, +

The nng_stream_dialer_close and nng_stream_listener_close functions close the stream dialer or listener, preventing it from creating new connections. This will generally include closing any underlying file used for creating such connections. However, some requests may still be pending when this function returns, as it does not wait for the shutdown to complete.

-

The nng_stream_dialer_stop and nng_stream_listener_stop functions performs the same action, +

The nng_stream_dialer_stop and nng_stream_listener_stop functions performs the same action, but also wait until all outstanding requests are serviced, and the dialer or listener is completely stopped. Because they blocks, these functions must not be called in contexts where blocking is not allowed.

-

The nng_stream_dialer_free and nng_stream_listener_free function performs the same action as +

The nng_stream_dialer_free and nng_stream_listener_free function performs the same action as nng_stream_dialer_stop or nng_stream_listener_stop, but also deallocates the dialer or listener, and any associated resources.

@@ -4322,7 +4320,7 @@ callbacks are running that could reference an object after it is deallocated.

Making Outgoing Connections 
void nng_stream_dialer_dial(nng_stream_dialer *dialer, nng_aio *aio);
-

The nng_stream_dialer_dial initiates an outgoing connection asynchronously, using the nng_aio aio. +

The nng_stream_dialer_dial initiates an outgoing connection asynchronously, using the nng_aio aio. If it successfully establishes a connection, it creates an nng_stream, which can be obtained as the first output result on aio using the nng_aio_get_output function with index zero.

@@ -4356,10 +4354,10 @@ stream = nng_aio_get_output(aio, 0); 
nng_err nng_stream_listener_listen(nng_stream_listener *listener);
 void nng_stream_listener_accept(nng_stream_listener *listener, nng_aio *aio);
-

Accepting incoming connections is performed in two steps. The first step, nng_stream_listener_listen is to setup for +

Accepting incoming connections is performed in two steps. The first step, nng_stream_listener_listen is to setup for listening. For a TCP implementation of this, for example, this would perform the bind and the listen steps. This will bind to the address represented by the URL that was specific when the listener was created with nng_stream_listener_alloc.

-

In the second step, nng_stream_listener_accept accepts an incoming connection on listener asynchronously, using the nng_aio aio. +

In the second step, nng_stream_listener_accept accepts an incoming connection on listener asynchronously, using the nng_aio aio. If an incoming connection is accepted, it will be represented as an nng_stream, which can be obtained from the aio as the first output result using the nng_aio_get_output function with index zero.

Example 3: Accepting an Inbound Stream

@@ -4386,14 +4384,12 @@ if (nng_aio_result(aio) != 0) { stream = nng_aio_get_output(aio, 0);

Stream Factory Options

-
nng_err nng_stream_dialer_get_addr(nng_stream_dialer *dialer, const char *opt, nng_sockaddr *valp);
-nng_err nng_stream_dialer_get_bool(nng_stream_dialer *dialer, const char *opt, bool *valp);
+
nng_err nng_stream_dialer_get_bool(nng_stream_dialer *dialer, const char *opt, bool *valp);
 nng_err nng_stream_dialer_get_int(nng_stream_dialer *dialer, const char *opt, int *valp);
 nng_err nng_stream_dialer_get_ms(nng_stream_dialer *dialer, const char *opt, nng_duration *valp);
 nng_err nng_stream_dialer_get_size(nng_stream_dialer *dialer, const char *opt, size_t *valp);
 nng_err nng_stream_dialer_get_string(nng_stream_dialer *dialer, const char *opt, const char **valp);
 
-nng_err nng_stream_listener_get_addr(nng_stream_listener *listener, const char *opt, nng_sockaddr *valp);
 nng_err nng_stream_listener_get_bool(nng_stream_listener *listener, const char *opt, bool *valp);
 nng_err nng_stream_listener_get_int(nng_stream_listener *listener, const char *opt, int *valp);
 nng_err nng_stream_listener_get_ms(nng_stream_listener *listener, const char *opt, nng_duration *valp);
@@ -4407,14 +4403,14 @@ nng_err nng_stream_dialer_set_ms(nng_stream_dialer *dialer, const char *opt, nng
 nng_err nng_stream_dialer_set_size(nng_stream_dialer *dialer, const char *opt, size_t val);
 nng_err nng_stream_dialer_set_string(nng_stream_dialer *dialer, const char *opt, const char *val);
 
-nng_err nng_stream_listener_set_addr(nng_stream_listener *listener, const char *opt, const nng_sockaddr *val);
 nng_err nng_stream_listener_set_bool(nng_stream_listener *listener, const char *opt, bool val);
 nng_err nng_stream_listener_set_int(nng_stream_listener *listener, const char *opt, int val);
 nng_err nng_stream_listener_set_ms(nng_stream_listener *listener, const char *opt, nng_duration val);
 nng_err nng_stream_listener_set_size(nng_stream_listener *listener, const char *opt, size_t val);
 nng_err nng_stream_listener_set_string(nng_stream_listener *listener, const char *opt, const char *val);
 

-

+

+
 
 
 
@@ -4436,8 +4432,6 @@ nng_err nng_stream_listener_set_string(nng_stream_listener *listener, const char
 
 
 
-
-
 These functions are used to retrieve or change the value of an option named opt from the stream dialer or listener.
 The nng_stream_dialer_get_ and nng_stream_listener_get_ function families retrieve the value, and store it in the location valp references.
 The nng_stream_dialer_set_ and nng_stream_listener_set_ function families change the value for the dialer or listener, taking it from val.

@@ -4447,12 +4441,12 @@ are available, and which type they may be accessed using.

 the string is only valid as long as the associated object remains open.

 
In the case of nng_stream_dialer_set_string and nng_stream_listener_set_string, the string contents are copied if necessary, so that the caller
 need not retain the value referenced once the function returns.

-
In the case of nng_stream_dialer_set_addr and nng_stream_listener_set_addr, the contents of addr are copied if necessary, so that the caller
+
In the case of nng_stream_dialer_set_addr, the contents of addr are copied if necessary, so that the caller
 need not retain the value referenced once the function returns.

 
Example 4: Socket Activation

-
Some nng_stream_listener objects, depending on the underlying transport and platform, can support a technique known as “socket activation”,
+
Some nng_stream_listener objects, depending on the underlying transport and platform, can support a technique known as “socket activation”,
 where the file descriptor used for listening and accepting is supplied externally, such as by a system service manager.
-In this case, the application supplies the file descriptor or SOCKET object using the NNG_OPT_LISTEN_FD option,
+In this case, the application supplies the file descriptor or SOCKET object using the NNG_OPT_LISTEN_FD option,
 instead of calling nng_stream_listener_listen.

 

 

@@ -4480,13 +4474,13 @@ nng_err nng_stream_dialer_set_tls(nng_stream_listener *dialer, nng_tls_config *t
 nng_err nng_stream_listener_get_tls(nng_stream_listener *listener, nng_tls_config **tlsp);
 nng_err nng_stream_listener_set_tls(nng_stream_listener *listener, nng_tls_config *tls);
-

Both nng_stream_dialer and nng_stream_listener objects may support configuration of TLS parameters. -The nng_stream_dialer_set_tls and nng_stream_listener_set_tls functions support setting the +

Both nng_stream_dialer and nng_stream_listener objects may support configuration of TLS parameters. +The nng_stream_dialer_set_tls and nng_stream_listener_set_tls functions support setting the configuration of a nng_tls_config object supplied by tls on dialer or listener. This must be performed before the listener starts listening with nng_stream_listener_listen, or the dialer starts an outgoing connection as a result of nng_stream_dialer_dial.

The configuration object that was previously established (which may be a default if one was not explicitly -configured) can be obtained with the nng_stream_dialer_get_tls and nng_stream_listener_get_tls. +configured) can be obtained with the nng_stream_dialer_get_tls and nng_stream_listener_get_tls. They will return a pointer to the nng_tls_config object in question at the location referenced by tlsp.

@@ -7733,7 +7727,7 @@ relative to the root directory.

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 @@ -7758,14 +7752,15 @@ longer than 128 bytes, including the ipc:// prefix.

Abstract sockets use a URI-encoded name after the abstract:// scheme, which allows arbitrary values to be conveyed in the path, including embedded NUL bytes. For example, the name "a\0b" would be represented as abstract://a%00b.

-
+

- tip + note

-

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.

+

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.

Abstract sockets do not have any representation in the file system, and are automatically freed by @@ -7782,8 +7777,6 @@ except for abstract sockets, which use nng_soc where supported by the underlying platform.

- - @@ -8077,11 +8070,9 @@ the actual structure is either of type

The following transport options are supported by this transport, where supported by the underlying platform.

OptionTypeDescription
NNG_OPT_IPC_PERMISSIONSintSettable on listeners before they start, this is the UNIX file mode used when creating the socket.
NNG_OPT_LOCADDRnng_sockaddrLocal socket address, either nng_sockaddr_ipc or nng_sockaddr_abstract.
NNG_OPT_REMADDRnng_sockaddrRemote socket address, either nng_sockaddr_ipc or nng_sockaddr_abstract.
NNG_OPT_PEER_GIDintRead only option, returns the group ID of the process at the other end of the socket, if platform supports it.
NNG_OPT_PEER_PIDintRead only option, returns the processed ID of the process at the other end of the socket, if platform supports it.
NNG_OPT_PEER_UIDintRead only option, returns the user ID of the process at the other end of the socket, if platform supports it.
- - - +
OptionTypeDescription
NNG_OPT_LOCADDRnng_sockaddrThe locally bound address, will be either nng_sockaddr_in or nng_sockaddr_in6.
NNG_OPT_REMADDRnng_sockaddrThe remote peer address, will be either nng_sockaddr_in or nng_sockaddr_in6. Only valid for pipe and dialer objects.
NNG_OPT_RECVMAXSZsize_tMaximum size of incoming messages, will be limited to at most 65000.
NNG_OPT_UDP_COPY_MAXsize_tThreshold above which received messages are “loaned” up, rather than a new message being allocated and copied into.
NNG_OPT_UDP_BOUND_PORTintThe locally bound UDP port number (1-65535), read-only for listener objects only.
NNG_OPT_BOUND_PORTintThe locally bound UDP port number (1-65535), read-only for listener objects only.

Maximum Message Size

@@ -8405,6 +8396,12 @@ to when dialing, by using the local address in front of the destination 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 Address Options Removed

+

The NNG_OPT_REMADDR and NNG_OPT_LOCADDR options are 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. Functions formerly used to configure these are +removed as well.

IPC Option Type Changes

The types of NNG_OPT_PEER_GID, NNG_OPT_PEER_PID, NNG_OPT_PEER_UID, and NNG_OPT_PEER_ZONEID have changed from uint64_t to int. The underlying platforms all use 32-bit quantities for these.

@@ -8447,6 +8444,7 @@ and are thus removed:

  • nng_stream_listener_set_ptr
  • nng_stream_listener_get_uint64
  • nng_stream_listener_set_uint64
    • +
  • nng_stream_listener_get_addr
  • nng_ctx_get_ptr (not documented)
  • nng_ctx_set_ptr (not documented)
    • @@ -8471,6 +8469,8 @@ such as one ending in a suffix like _bool (to access a boolnng_stream_listener_set

    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 @@ -8494,6 +8494,11 @@ directly:

    The latter option is a hint for transports and intended to facilitate early detection (and possibly avoidance of extra allocations) of oversize messages, 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 have been replaced by functions instead of options. @@ -8565,6 +8570,9 @@ They may silently truncate data.

    The HTTP handler objects may not be modified once in use. Previously this would fail with NNG_EBUSY. These checks are removed now, but debug builds will assert if an application tries to do so.

    +

    The nng_http_server_get_addr function is removed. Instead there is now +[nng_http_server_get_port] which can be used to obtain the port actually bound if the server +was configured with port 0.

    WebSocket API

    The NNG_OPT_WSS_REQUEST_HEADERS, NNG_OPT_WSS_RESPONSE_HEADERS and NNG_OPT_WS_OPT_WS_REQUEST_HEADERS, NNG_OPT_WS_RESPONSE_HEADERS have been removed.

    @@ -8590,6 +8598,15 @@ See nng_ar

    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, 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:

    +
    char url[256];
+snprintf(url, sizeof (url), `abstract://my-app-%08x-%08x-%08x-%08x",
+    nni_random(), nni_random(), nni_random(), nni_random());
+