diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/man/nng_ipc.7.adoc | 42 | ||||
| -rw-r--r-- | docs/man/nng_sockaddr.5.adoc | 28 | ||||
| -rw-r--r-- | docs/man/nng_sockaddr_abstract.5.adoc | 77 |
3 files changed, 131 insertions, 16 deletions
diff --git a/docs/man/nng_ipc.7.adoc b/docs/man/nng_ipc.7.adoc index 0d75e8d3..856a00ac 100644 --- a/docs/man/nng_ipc.7.adoc +++ b/docs/man/nng_ipc.7.adoc @@ -1,6 +1,6 @@ = nng_ipc(7) // -// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // // This document is supplied under the terms of the MIT License, a @@ -38,7 +38,9 @@ Other platforms may have different implementation strategies. This transport is generally built-in to the core, so no extra steps to use it should be necessary. -=== URI Format +=== URI Formats + +==== Traditional Names (((URI, `ipc://`))) This transport uses URIs using the scheme `ipc://`, followed by a path @@ -58,15 +60,47 @@ To ensure maximum portability and safety, absolute paths are recommended whenever possible. NOTE: If compatibility with legacy _nanomsg_ applications is required, -then pathnames must not be longer than 122 bytes, including the final +then path names must not be longer than 122 bytes, including the final `NUL` byte. This is because legacy versions of _nanomsg_ cannot express URLs longer than 128 bytes, including the `ipc://` prefix. +==== UNIX Aliases + +(((URI, `unix://`))) +The `unix://` scheme is an alias for `ipc://` and can be used inter-changeably, but only +on POSIX systems. + +The purpose of this scheme is to support a future transport making use of `AF_UNIX` +on Windows systems, at which time it will be necessary to discriminate between +the Named Pipes and the `AF_UNIX` based transports. + +==== Abstract Names + +(((URI, `abstract://`))) +On Linux, this transport also can support abstract sockets. +Abstract sockets use a URI-encoded name after the 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: 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_ cannot represent an abstract socket with the empty name. + +NOTE: 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 +the system when no longer in use. +Abstract sockets ignore socket permissions, but it is still possible to determine the credentials +of the peer with `NNG_OPT_PEER_UID`, etc. + === Socket Address When using an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] structure, -the actual structure is of type xref:nng_sockaddr_ipc.5.adoc[`nng_sockaddr_ipc`]. +the actual structure is of type xref:nng_sockaddr_ipc.5.adoc[`nng_sockaddr_ipc`], +except for abstract sockets, which use xref:nng_sockaddr_abstract.5.adoc[`nng_sockaddr_abstract`]. === Transport Options diff --git a/docs/man/nng_sockaddr.5.adoc b/docs/man/nng_sockaddr.5.adoc index cf347f66..cd10cab4 100644 --- a/docs/man/nng_sockaddr.5.adoc +++ b/docs/man/nng_sockaddr.5.adoc @@ -20,21 +20,23 @@ nng_sockaddr - socket address #include <nng/nng.h> typedef union nng_sockaddr { - uint16_t s_family; - nng_sockaddr_ipc s_ipc; - nng_sockaddr_inproc s_inproc; - nng_sockaddr_in s_in; - nng_sockaddr_in6 s_in6; - nng_sockaddr_zt s_zt; + uint16_t s_family; + nng_sockaddr_ipc s_ipc; + nng_sockaddr_inproc s_inproc; + nng_sockaddr_in s_in; + nng_sockaddr_in6 s_in6; + nng_sockaddr_zt s_zt; + nng_sockaddr_abstract s_abstract; } nng_sockaddr; enum sockaddr_family { - NNG_AF_UNSPEC = 0, - NNG_AF_INPROC = 1, - NNG_AF_IPC = 2, - NNG_AF_INET = 3, - NNG_AF_INET6 = 4, - NNG_AF_ZT = 5, + NNG_AF_UNSPEC = 0, + NNG_AF_INPROC = 1, + NNG_AF_IPC = 2, + NNG_AF_INET = 3, + NNG_AF_INET6 = 4, + NNG_AF_ZT = 5, + NNG_AF_ABSTRACT = 6 }; ---- @@ -70,12 +72,14 @@ The values of `s_family` are as follows: `NNG_AF_INET`:: Address for TCP/IP (v4) communication. The `s_in` member is valid. `NNG_AF_INET6`:: Address for TCP/IP (v6) communication. The `s_in6` member is valid. `NNG_AF_ZT`:: Address for ZeroTier transport (xref:nng_zerotier.7.adoc[nng_zerotier(7)]). The `s_zt` member is valid. +`NNG_AF_ABSTRACT`:: Address for an abstract UNIX domain socket. The `s_abstract` member is valid. Please see the manual pages for each individual type for more information. == SEE ALSO [.text-left] +xref:nng_sockaddr_abstract.5.adoc[nng_sockaddr_abstract(5)], xref:nng_sockaddr_in.5.adoc[nng_sockaddr_in(5)], xref:nng_sockaddr_in6.5.adoc[nng_sockaddr_in6(5)], xref:nng_sockaddr_inproc.5.adoc[nng_sockaddr_inproc(5)], diff --git a/docs/man/nng_sockaddr_abstract.5.adoc b/docs/man/nng_sockaddr_abstract.5.adoc new file mode 100644 index 00000000..ccdbb6c5 --- /dev/null +++ b/docs/man/nng_sockaddr_abstract.5.adoc @@ -0,0 +1,77 @@ += nng_sockaddr_abstract(5) +// +// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_sockaddr_abstract - abstract IPC socket address + +== SYNOPSIS + +[source,c] +---- +#include <nng/nng.h> + +enum sockaddr_family { + NNG_AF_ABSTRACT = 6, +}; + +typedef struct { + uint16_t sa_family; + uint16_t sa_len; + char sa_name[107]; +} nng_sockaddr_abstract; +---- + +== DESCRIPTION + +(((socket, address, abstract))) An `nng_sockaddr_abstract` is the flavor of xref:nng_sockaddr.5.adoc[`nng_sockaddr`] +used to represent addresses associated with IPC communication using "`abstract`" sockets. + +Abstract sockets are only supported on Linux at present. +These sockets have a name that is simply an array of bytes, with no special meaning. +Abstract sockets also have no presence in the file system, do not honor any permissions, and are automatically +cleaned up by the operating system when no longer in use. + +NOTE: Support for abstract sockets is a new feature in _NNG_, and it is only available on Linux. +As such their use is not recommended for portable applications. + +The following structure members are present: + +`sa_family`:: +This field will always have the value ((`NNG_AF_ABSTRACT`)). + +`sa_len`:: +This field provides the name of the length stored in `sa_name`. + +`sa_name`:: +This field holds the name of the abstract socket. +The bytes of name can have any value, including zero. + +NOTE: The name does _not_ include the leading `NUL` byte used on Linux to discriminate between +abstract and path name sockets. + +=== Auto Bind + +An empty value (`sa_len` equal to zero) can be used on listening sockets to request the +system allocate a name. +On Linux systems, this will result in a name with either 5 or 8 hexadecimal ASCII characters. +The name chosen can be obtained by retrieving the `NNG_OPT_LOCADDR` option on the listening entity. + +NOTE: Because a zero length name is used to indicate auto bind be used, it is impossible to specify +an actual empty name. This name are not supported by _NNG_, although the underlying system can support it. +The use of that name is inadvisable anyway. + + +== SEE ALSO + +[.text-left] +xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], +xref:nng_ipc.7.adoc[nng_ipc(7)] +xref:nng.7.adoc[nng(7)] |