From 09bf59112e559c3addba3dc22ea864324a1d24be Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 9 Nov 2020 14:33:15 -0800 Subject: Manual page updates for tip (#1333) Co-authored-by: Staysail Systems, Inc --- man/tip/_toc.html | 2 + man/tip/index.html | 8 +++ man/tip/libnng.3.html | 4 ++ man/tip/nng_ipc.7.html | 77 +++++++++++++++++++- man/tip/nng_sockaddr.5.html | 37 ++++++---- man/tip/nng_sockaddr_abstract.5.html | 127 +++++++++++++++++++++++++++++++++ man/tip/nng_sockaddr_in6.5.html | 9 +++ man/tip/nng_sockaddr_ipc.5.html | 43 ++++++----- man/tip/nng_thread_set_name.3supp.html | 78 ++++++++++++++++++++ man/tip/nng_ws.7.html | 109 +++++++++++++++++++++++++++- 10 files changed, 458 insertions(+), 36 deletions(-) create mode 100644 man/tip/nng_sockaddr_abstract.5.html create mode 100644 man/tip/nng_thread_set_name.3supp.html diff --git a/man/tip/_toc.html b/man/tip/_toc.html index c62d8b3d..c2135fc8 100644 --- a/man/tip/_toc.html +++ b/man/tip/_toc.html @@ -283,6 +283,7 @@
  • nng_random
  • nng_thread_create
  • nng_thread_destroy
    • +
  • nng_thread_set_name
  • Supplemental TLS Functions
    • @@ -315,6 +316,7 @@
  • nng_options
  • nng_pipe
  • nng_sockaddr
    • +
  • nng_sockaddr_abstract
  • nng_sockaddr_in
  • nng_sockaddr_in6
  • nng_sockaddr_inproc
    • diff --git a/man/tip/index.html b/man/tip/index.html index 24e759d8..5829d252 100644 --- a/man/tip/index.html +++ b/man/tip/index.html @@ -1195,6 +1195,10 @@ mutual exclusion locks, threading, time keeping, and similar needs.

    nng_thread_destroy(3supp)

    reap thread

    + +

    nng_thread_set_name(3supp)

    +

    set thread name

    + @@ -1356,6 +1360,10 @@ applications need will use.

    socket address

    +

    nng_sockaddr_abstract(5)

    +

    abstract IPC socket address

    + +

    nng_sockaddr_in(5)

    IPv4 socket address

    diff --git a/man/tip/libnng.3.html b/man/tip/libnng.3.html index a4d6a875..99c4ec95 100644 --- a/man/tip/libnng.3.html +++ b/man/tip/libnng.3.html @@ -837,6 +837,10 @@ as a convenience to aid in creating portable applications.

    nng_thread_destroy()

    reap thread

    + +

    nng_thread_set_name()

    +

    set thread name

    + diff --git a/man/tip/nng_ipc.7.html b/man/tip/nng_ipc.7.html index 1aa55e92..ed2c43cc 100644 --- a/man/tip/nng_ipc.7.html +++ b/man/tip/nng_ipc.7.html @@ -42,7 +42,9 @@ 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 @@ -89,7 +91,7 @@ whenever possible. 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. @@ -98,11 +100,80 @@ 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.

    +
    +
    + + + + + +
    + + +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 cannot represent an abstract socket with the empty name. +
    +
    +
    + + + + + +
    + + +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 nng_sockaddr structure, -the actual structure is of type nng_sockaddr_ipc.

    +the actual structure is of type nng_sockaddr_ipc, +except for abstract sockets, which use nng_sockaddr_abstract.

    diff --git a/man/tip/nng_sockaddr.5.html b/man/tip/nng_sockaddr.5.html index 4897e271..467da3b4 100644 --- a/man/tip/nng_sockaddr.5.html +++ b/man/tip/nng_sockaddr.5.html @@ -19,21 +19,23 @@ layout: manpage_v2 
    #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
 };
    @@ -121,6 +123,14 @@ specific member should be used.

    Address for ZeroTier transport (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.

    + +
    @@ -132,7 +142,8 @@ specific member should be used.

    SEE ALSO

    -

    nng_sockaddr_in(5), +

    nng_sockaddr_abstract(5), +nng_sockaddr_in(5), nng_sockaddr_in6(5), nng_sockaddr_inproc(5), nng_sockaddr_ipc(5), diff --git a/man/tip/nng_sockaddr_abstract.5.html b/man/tip/nng_sockaddr_abstract.5.html new file mode 100644 index 00000000..1eec3a30 --- /dev/null +++ b/man/tip/nng_sockaddr_abstract.5.html @@ -0,0 +1,127 @@ +--- +version: tip +layout: manpage_v2 +--- +

    nng_sockaddr_abstract(5)

    +
    +

    NAME

    +
    +
    +

    nng_sockaddr_abstract - abstract IPC socket address

    +
    +
    +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #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

    +
    +
    +

    An nng_sockaddr_abstract is the flavor of 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.

    +
    +
    + + + + + +
    + + +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.

    +
    +
    +
    +
    + + + + + +
    + + +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.

    +
    +
    + + + + + +
    + + +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

    +
    +
    +

    nng_sockaddr(5), +nng_ipc(7) +nng(7)

    +
    +
    +
    diff --git a/man/tip/nng_sockaddr_in6.5.html b/man/tip/nng_sockaddr_in6.5.html index 5013666f..6799d385 100644 --- a/man/tip/nng_sockaddr_in6.5.html +++ b/man/tip/nng_sockaddr_in6.5.html @@ -26,6 +26,7 @@ layout: manpage_v2 uint16_t sa_family; uint16_t sa_port; uint8_t sa_addr[16]; + uint32_t sa_scope; } nng_sockaddr_in6;
    @@ -63,6 +64,14 @@ for IPv4 addresses.

    This field holds the IP address in network-byte order.

    +
    sa_scope
    +
    +

    This is the scope, and is typically used with link local + addresses to identify a specific interface. The details of + this are specific to the operating system. This value is + presented identically to the underlying system’s, including + any byte order considerations.

    +
    diff --git a/man/tip/nng_sockaddr_ipc.5.html b/man/tip/nng_sockaddr_ipc.5.html index c2ad0cdb..90e9b04c 100644 --- a/man/tip/nng_sockaddr_ipc.5.html +++ b/man/tip/nng_sockaddr_ipc.5.html @@ -24,7 +24,7 @@ layout: manpage_v2 typedef struct { uint16_t sa_family; - uint16_t sa_path[128]; + char sa_path[128]; } nng_sockaddr_ipc;
    @@ -34,9 +34,8 @@ layout: manpage_v2

    DESCRIPTION

    -

    An nng_sockaddr_ipc is the flavor of nng_sockaddr -used to represent addresses associated with IPC communication -using the ipc transport.

    +

    An nng_sockaddr_ipc is the flavor of nng_sockaddr +used to represent addresses associated with IPC communication using the ipc transport.

    The following structure members are present:

    @@ -49,12 +48,9 @@ using the ipc transport.

    sa_path
    -

    This field holds the C string corresponding to path name where the - IPC socket is located. - For systems using UNIX domain sockets, this will be an absolute - path name in the file system, where the UNIX domain socket is located. - For Windows systems, this is the path name of the Named Pipe, without - the leading \\.pipe\ portion, which will be automatically added.

    +

    This field holds the C string corresponding to path name where the IPC socket is located. +For systems using UNIX domain sockets, this will be a path name in the file system, where the UNIX domain socket is located. +For Windows systems, this is the path name of the Named Pipe, without the leading \\.pipe\ portion, which will be automatically added.

    @@ -65,7 +61,7 @@ using the ipc transport.

    -At this time, there is no support for Linux abstract sockets. +At this time, there is no support for abstract sockets. @@ -77,11 +73,22 @@ At this time, there is no support for Linux abstract sockets. -In order to ensure maximum compatibility, applications should avoid -hard coding the size of the sa_path member explicitly, but use the +In order to ensure maximum compatibility, applications should avoid hard coding the size of the sa_path member explicitly, but use the sizeof operator to determine its actual size at compile time. -Furthermore, the size is guaranteed to be at least 128, but paths of -this length may not be supported on all systems. +Furthermore, the size is guaranteed to be at least 128, but paths of this length may not be supported on all systems. + + + +
    +
    + + + +
    + + +Portable applications should restrict themselves to path names of not more than 90 bytes. Most systems have +limits around 100 bytes, but at least one system (HP-UX) is restricted to not more than 92 bytes including the NUL.
    @@ -93,11 +100,9 @@ this length may not be supported on all systems. -If compatibility with legacy nanomsg applications is required, -then pathnames must not be longer than 122 bytes, including the final +If compatibility with legacy nanomsg applications is required, 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. +This is because legacy versions of nanomsg cannot express URLs longer than 128 bytes, including the ipc:// prefix. diff --git a/man/tip/nng_thread_set_name.3supp.html b/man/tip/nng_thread_set_name.3supp.html new file mode 100644 index 00000000..2738d5d1 --- /dev/null +++ b/man/tip/nng_thread_set_name.3supp.html @@ -0,0 +1,78 @@ +--- +version: tip +layout: manpage_v2 +--- +

    nng_thread_set_name(3supp)

    +
    +

    NAME

    +
    +
    +

    nng_thread_set_name - set thread name

    +
    +
    +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+void nng_set_thread_name(nng_thread *thread, const char *name);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_thread_set_name() function attempts to set the name for the thread to name.

    +
    +
    +

    If thread is NULL, then the name is set for the current thread.

    +
    +
    +

    Support for this, and how names are exposed, varies between platform implementations. +This function is intended to facilitate debugging applications that may have many threads.

    +
    +
    + + + + + +
    + + +Internal threads created by NNG will have names beginning with nng:. +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng_thread_create(3supp), +nng(7)

    +
    +
    +
    diff --git a/man/tip/nng_ws.7.html b/man/tip/nng_ws.7.html index b31496d8..dd252cc5 100644 --- a/man/tip/nng_ws.7.html +++ b/man/tip/nng_ws.7.html @@ -68,6 +68,51 @@ port 80 on localhost, with the path /app/pubsub.

    Otherwise the format is the same as for regular WebSockets.

    +

    A URI may be restricted to IPv6 using the scheme ws6:// or wss6://, and may +be restricted to IPv4 using the scheme ws4:// or wss4://.

    +
    +
    + + + + + +
    + + +Specifying ws6:// or wss6:// may not prevent IPv4 hosts from being used with +IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with +listeners. +The details of this varies across operating systems. +
    +
    +
    + + + + + +
    + + +The ws4:// , ws6://, wss4:// and wss6:// schemes are specific to NNG, +and might not be understood by other implementations. +
    +
    +
    + + + + + +
    + + +We recommend using either numeric IP addresses, or names that are +specific to either IPv4 or IPv6 to prevent confusion and surprises. +
    +
    +

    When specifying IPv6 addresses, the address must be enclosed in square brackets ([]) to avoid confusion with the final colon separating the port.

    @@ -157,7 +202,7 @@ only available for wss:// endpoints.
    NNG_OPT_WS_REQUEST_HEADERS
    -

    (string) Concentation of multiple lines terminated +

    (string) Concatenation of multiple lines terminated by CRLF sequences, that can be used to add further headers to the HTTP request sent when connecting. This option can be set on dialers, and retrieved from pipes.

    @@ -169,6 +214,68 @@ by CRLF sequences, that can be used to add further headers to the HTTP response sent when connecting. This option can be set on listeners, and retrieved from pipes.

    +
    NNG_OPT_WS_RECV_TEXT
    +
    +

    (bool) Enable receiving of TEXT frames at the WebSocket layer. +This option should only be used with the low level +nng_stream API. +When set, the stream will accept in-bound TEXT frames as well as BINARY frames.

    +
    +
    +
    +
    + + + + + +
    + + +The SP protocols (such as REQ) require BINARY frames as they pass binary protocol data. +Hence this option should not be used with such protocols. +
    +
    +
    + + + + + +
    + + +RFC 6455 requires that TEXT frames be discarded and the connection closed if the frame does not contain valid UTF-8 data. +NNG does not perform any such validation. +Applications that need to be strictly conformant should check for this themselves. +
    +
    +
    +
    +
    NNG_OPT_WS_SEND_TEXT
    +
    +

    (bool) Enable sending of TEXT frames at the WebSocket layer. +This option should only be used with the low level +nng_stream API. +When set, the stream will send TEXT frames instead of BINARY frames.

    +
    +
    +
    +
    + + + + + +
    + + +NNG does not check the frame data, and will attempt to send whatever the client requests. +Peers that are compliant with RFC 6455 will discard TEXT frames (and break the connection) if they do not contain valid UTF-8. +
    +
    +
    +
    NNG_OPT_TLS_CONFIG

    (nng_tls_config *) The underlying TLS -- cgit v1.2.3-70-g09d2