From 7092fa31f447d1750dc560cea49052b3e4f57620 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 13 Mar 2018 21:15:40 -0700 Subject: Introduce nng_options, nng_setopt, nng_getopt manual pages. This starts a new section 5 for generic topics, and sets up some links for things like nng_duration and nng_socket types. There will some day be an nng_errors(5) page as well. Some initial work towards indexing terms for these pages is done now too. (Indexing will mostly be useful when generating book forms of this documentation.) --- docs/man/nng_dialer_getopt.adoc | 38 +++-- docs/man/nng_dialer_setopt.adoc | 6 + docs/man/nng_getopt.adoc | 122 ++++++++++++++++ docs/man/nng_listener_getopt.adoc | 5 + docs/man/nng_listener_setopt.adoc | 6 + docs/man/nng_options.adoc | 285 ++++++++++++++++++++++++++++++++++++++ docs/man/nng_setopt.adoc | 116 ++++++++++++++++ docs/man/nng_zerotier.adoc | 62 ++++----- docs/man/nngcat.adoc | 16 ++- docs/man/publish.sh | 1 + 10 files changed, 605 insertions(+), 52 deletions(-) create mode 100644 docs/man/nng_getopt.adoc create mode 100644 docs/man/nng_options.adoc create mode 100644 docs/man/nng_setopt.adoc diff --git a/docs/man/nng_dialer_getopt.adoc b/docs/man/nng_dialer_getopt.adoc index 7c6fc3ad..c4263262 100644 --- a/docs/man/nng_dialer_getopt.adoc +++ b/docs/man/nng_dialer_getopt.adoc @@ -20,10 +20,15 @@ nng_dialer_getopt - get dialer option #include int nng_dialer_getopt(nng_dialer d, const char *opt, void *val, size_t *valszp); + int nng_dialer_getopt_int(nng_dialer d, const char *opt, int *ivalp); + int nng_dialer_getopt_ms(nng_dialer d, const char *opt, nng_duration *durp); + int nng_dialer_getopt_ptr(nng_dialer d, const char *opt, void **ptr); + int nng_dialer_setopt_size(nng_dialer d, const char *opt, size_t *zp); + int nng_dialer_getopt_uint64(nng_dialer d, const char *opt, uint64_t *u64p); ----------- @@ -40,30 +45,37 @@ In all of these forms, the option _opt_ is retrieved from the dialer _d_. The details of the type, size, and semantics of the option will depend on the actual option, and will be documented with the option itself. +=== Untyped Form + The first form of this function, `nng_dialer_getopt()`, can be used to -retrieve the value of any option. It is untyped. The caller must store -a pointer to a buffer to receive the value in _val_, and the size of the -buffer shall be stored at the location referenced by _valszp_. +retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced +by _valszp_. When the function returns, the actual size of the data copied (or that would have been copied if sufficient space were present) is stored at -the location referened by _valszp_. If the caller's buffer is not large -enough to hold the entire object, then the copy is truncated. Therefore -the caller should validate that the returned size in _valszp_ does not +the location referened by _valszp_. +If the caller's buffer is not large +enough to hold the entire object, then the copy is truncated. +Therefore the caller should validate that the returned size in _valszp_ does not exceed the original buffer size to check for truncation. It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. This can be used to determine the size of the buffer needed to receive the object. -Generally, it will be easier to use one of the typed forms instead. Note -however that no validation that the option is actually of the associated +=== Typed Forms + +Generally, it will be easier to use one of the typed forms instead. +Note however that no validation that the option is actually of the associated type is performed, so the caller must take care to use the *correct* typed form. The second form, `nng_dialer_getopt_int()`, -is for options which take an integer (or boolean). The value will -be stored at _ivalp_. For booleans the value will be eiher 0 (false) or 1 (true). +is for options which take an integer (or boolean). +The value will be stored at _ivalp_. +For booleans the value will be eiher 0 (false) or 1 (true). The third form, `nng_dialer_getopt_ms()`, is used to retrieve time durations (such as timeouts), stored in _durp_ as a number of milliseconds. @@ -71,8 +83,8 @@ The third form, `nng_dialer_getopt_ms()`, is used to retrieve time durations the special value `NNG_DUR_DEFAULT` means a context-specific default.) The fourth form, `nng_dialer_getopt_ptr()`, is used to retrieve a -pointer _ptr_ to structured data. The data referenced by _ptr_ is -generally managed using other functions. +pointer _ptr_ to structured data. +The data referenced by _ptr_ is generally managed using other functions. Note that this form is somewhat special in that the object is generally not copied, but instead the *pointer* to the object is copied. @@ -80,7 +92,7 @@ The fifth form, `nng_dialer_getopt_size()`, is used to retrieve a size into the pointer _zp_, typically for buffer sizes, message maximum sizes, and similar options. -The sixth form, `nng_diale_getopt_uint64()`, is used to retrieve a +The sixth form, `nng_dialer_getopt_uint64()`, is used to retrieve a 64-bit unsigned value into the value referenced by _u64p_. This is typically used for options related to identifiers, network numbers, and similar. diff --git a/docs/man/nng_dialer_setopt.adoc b/docs/man/nng_dialer_setopt.adoc index 8bd6a04b..d6a94714 100644 --- a/docs/man/nng_dialer_setopt.adoc +++ b/docs/man/nng_dialer_setopt.adoc @@ -21,11 +21,17 @@ nng_dialer_setopt - set dialer option int nng_dialer_setopt(nng_dialer d, const char *opt, const void *val, size_t valsz); + int nng_dialer_setopt_int(nng_dialer d, const char *opt, int ival); + int nng_dialer_setopt_ms(nng_dialer d, const char *opt, nng_duration dur); + int nng_dialer_setopt_ptr(nng_dialer d, const char *opt, void *ptr); + int nng_dialer_setopt_size(nng_dialer d, const char *opt, size_t z); + int nng_dialer_setopt_string(nng_dialer d, const char *opt, const char *str); + int nng_dialer_setopt_uint64(nng_dialer d, const char *opt, uint64_t u64); ----------- diff --git a/docs/man/nng_getopt.adoc b/docs/man/nng_getopt.adoc new file mode 100644 index 00000000..322927cc --- /dev/null +++ b/docs/man/nng_getopt.adoc @@ -0,0 +1,122 @@ += nng_getopt(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_getopt - get socket option + +== SYNOPSIS + +[source, c] +----------- +#include + +int nng_getopt(nng_socket s, const char *opt, void *val, size_t *valszp); + +int nng_getopt_int(nng_socket s, const char *opt, int *ivalp); + +int nng_getopt_ms(nng_socket s, const char *opt, nng_duration *durp); + +int nng_getopt_ptr(nng_socket s, const char *opt, void **ptr); + +int nng_getopt_size(nng_socket s, const char *opt, size_t *zp); + +int nng_getopt_uint64(nng_socket s, const char *opt, uint64_t *u64p); +----------- + +== DESCRIPTION + +The `((nng_getopt))()` functions are used to retrieve option values for +the socket _s_. +The actual options that may be retrieved in this way vary. +A number of them are documented in <>. + +Additionally transport-specific options and protocol-specific options are +documented with the transports and protocols themselves. + +In all of these forms, the option _opt_ is retrieved from the socket _s_. +The forms vary based on the type of the option they take. + +TIP: Generally, it will be easier to use one of the typed forms instead. + +NOTE: No validation that the option is actually of the associated +type is performed, so the caller must take care to use the *correct* typed form. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + + +`nng_getopt()`:: +This function is untyped can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced by +_valszp_. ++ +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referened by _valszp_. +If the caller's buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifyng that the +returned size in _valszp_ does not exceed the original buffer size. ++ +It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. + +`nng_getopt_int()`:: + +This function is for options which take an integer (`int`) or boolean (`bool`). +The value will be stored at _ivalp_. +For booleans the value will be eiher 0 (`false`) or 1 (`true`). + +`nng_getopt_ms()`:: +This function is used to retrieve time durations +(such as timeouts), stored in _durp_ as a number of milliseconds. +(The special value ((`NNG_DUR_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DUR_DEFAULT`)) means a context-specific default.) + +`nng_getopt_ptr()`:: +This function is used to retrieve a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +`nng_getopt_size()`:: +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_getopt_uint64()`:: +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_listener_getopt.adoc b/docs/man/nng_listener_getopt.adoc index 1218feeb..b79a4578 100644 --- a/docs/man/nng_listener_getopt.adoc +++ b/docs/man/nng_listener_getopt.adoc @@ -21,10 +21,15 @@ nng_listener_getopt - get listener option int nng_listener_getopt(nng_listener l, const char *opt, void *val, size_t *valszp); + int nng_listener_getopt_int(nng_listener l, const char *opt, int *ivalp); + int nng_listener_getopt_ms(nng_listener l, const char *opt, nng_duration *durp); + int nng_listener_getopt_ptr(nng_listener l, const char *opt, void **ptr); + int nng_listener_setopt_size(nng_listener l, const char *opt, size_t *zp); + int nng_listener_getopt_uint64(nng_listener l, const char *opt, uint64_t *u64p); ----------- diff --git a/docs/man/nng_listener_setopt.adoc b/docs/man/nng_listener_setopt.adoc index c231070e..87244510 100644 --- a/docs/man/nng_listener_setopt.adoc +++ b/docs/man/nng_listener_setopt.adoc @@ -21,11 +21,17 @@ nng_listener_setopt - set listener option int nng_listener_setopt(nng_listener l, const char *opt, const void *val, size_t valsz); + int nng_listener_setopt_int(nng_listener l, const char *opt, int ival); + int nng_listener_setopt_ms(nng_listener l, const char *opt, nng_duration dur); + int nng_listener_setopt_ptr(nng_listener l, const char *opt, void *ptr); + int nng_listener_setopt_size(nng_listener l, const char *opt, size_t z); + int nng_listener_setopt_string(nng_listener l, const char *opt, const char *str); + int nng_listener_setopt_uint64(nng_listener l, const char *opt, uint64_t u64); ----------- diff --git a/docs/man/nng_options.adoc b/docs/man/nng_options.adoc new file mode 100644 index 00000000..045618b3 --- /dev/null +++ b/docs/man/nng_options.adoc @@ -0,0 +1,285 @@ += nng_options(5) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_options - socket, dialer, listener, and pipe options + +== SYNOPSIS + +[source, c] +----------- +#include + +#define NNG_OPT_SOCKNAME "socket-name" +#define NNG_OPT_RAW "raw" +#define NNG_OPT_LINGER "linger" +#define NNG_OPT_RECVBUF "recv-buffer" +#define NNG_OPT_SENDBUF "send-buffer" +#define NNG_OPT_RECVFD "recv-fd" +#define NNG_OPT_SENDFD "send-fd" +#define NNG_OPT_RECVTIMEO "recv-timeout" +#define NNG_OPT_SENDTIMEO "send-timeout" +#define NNG_OPT_LOCADDR "local-address" +#define NNG_OPT_REMADDR "remote-address" +#define NNG_OPT_URL "url" +#define NNG_OPT_MAXTTL "ttl-max" +#define NNG_OPT_RECVMAXSZ "recv-size-max" +#define NNG_OPT_RECONNMINT "reconnect-time-min" +#define NNG_OPT_RECONNMAXT "reconnect-time-max" +----------- + +== DESCRIPTION + +This page documents the various standard options that can be used +with sockets (see `<>` +and `<>`), +dialers (see `<>` +and `<>`), +listeners (see `<>` +and `<>`), +and pipes (see `<>`). + +In addition to the options listed here, transports and protocols will generally +have some of their own options, which will be documented with the transport +or protocol. + +=== Options + +In the following list of options, the name of the option is supplied, +along with the data type of the underlying value. +Some options are only meaningful or supported in certain contexts; for +example there is no single meaningful address for a socket, since sockets +can have multiple dialers and endpoints associated with them. +An attempt has been made to include details about such restrictions in the +description of the option. + +[[NNG_OPT_LINGER]] +((`NNG_OPT_LINGER`)):: +(((lingering))) +(`<>`) +This is the linger time of the socket in milliseconds. +When this value is non-zero, then the system will +attempt to defer closing until it has undelivered data, or until the specified +timeout has expired. + +NOTE: Not all transports support lingering, and +so closing a socket or exiting the application can still result in the loss +of undelivered messages. + +[[NNG_OPT_LOCADDR]] +((`NNG_OPT_LOCADDR`)):: +(`<>`) +This read-only option may be used on listeners, dialers and connected pipes, and +represents the local address used for communication. +Not all transports support this option, and some transports may support it +listeners but not dialers. + +[[NNG_OPT_RAW]] +((`NNG_OPT_RAW`)):: +(((raw mode))) +(((cooked mode))) +(`bool`) +This option determines whether the socket is in "`raw`" mode. +If `true`, the socket is in "`raw`" mode, and if `false` the socket is +in "`cooked`" mode. +Raw mode sockets generally do not have any protocol-specific semantics applied +to them; instead the application is expected to perform such semantics itself. +(For example, in "`cooked`" mode an <> socket would +automatically copy message headers from a received message to the corresponding +reply, whereas in "`raw`" mode this is not done.) + +[[NNG_OPT_RECONNMINT]] +((`NNG_OPT_RECONNMINT`)):: +(((reconnect time, minimum))) +(`<>`) +This is the minimum amount of time (milliseconds) to wait before attempting +to establish a connection after a previous attempt has failed. +This can be set on a socket, but it can also be overridden on an individual +dialer. +The option is irrelevant for listeners. + +[[NNG_OPT_RECONNMAXT]] +((`NNG_OPT_RECONNMAXT`)):: +(((`NNG_OPT_RECONNMAXT`))) +(((reconnect time, maximum))) +(`<>`) +This is the maximum amount of time +(milliseconds) to wait before attempting to establish a connection after +a previous attempt has failed. +If this is non-zero, then the time between successive connection attempts +will start at the value of `<>`, +and grow exponentially, until it reaches this value. +If this value is zero, then no exponential +backoff between connection attempts is done, and each attempt will wait +the time specified by `<>`. +This can be set on a socket, but it can also be overridden on an individual +dialer. +The option is irrelevant for listeners. + +[[NNG_OPT_RECVBUF]] +((`NNG_OPT_RECVBUF`)):: +(((buffer, receive))) +(((receive, buffer))) +(`int`) +This is the depth of the socket's receive buffer as a number of messages. +Messages received by a transport may be buffered until the application +has accepted them for delivery. + +[[NNG_OPT_RECVFD]] +((`NNG_OPT_RECVFD`)):: +(((poll))) +(((select))) +(((receive, polling))) +(`int`) +This read-only option is used to obtain an integer file descriptor suitable +for use in `poll()`, `select()`, (or on Windows systems `WSApoll()`) and +similar functions. +This descriptor will be *readable* when a message is available for receiving +on the socket. +When no message is ready for receiving, then this file descriptor will *not* +be readable. + +IMPORTANT: Appplications should never attempt to read or write to the +returned file descriptor. +Furthermore, applications should not attempt to use the actual socket (of +type `<>`) with polling functions, +since it is merely an internal +identifier and will not necessarily referency any operting system object or +handle. + +TIP: While this option may help applications integrate into existing polling +loops, it is more efficient, and often easier, to use the asynchronous I/O +objects instead. See `<>`. + +[[NNG_OPT_RECVMAXSZ]] +((`NNG_OPT_RECVMAXSZ`)):: +(((receive, maximum size))) +(`size_t`) +This is the maximum message size that the will be accepted from a remote peer. +If a peer attempts to send a message larger than this, then the message +will be discarded. +If the value of this is zero, then no limit on message sizes is enforced. +This option exists to prevent certain kinds of denial-of-service attacks, +where a malicious agent can claim to want to send an extraordinarily +large message, without sending any data. +This option can be set for the socket, but may be overridden for on a +per-dialer or per-listener basis. + +NOTE: Some transports may have further message size restrictions! + +[[NNG_OPT_RECVTIMEO]] +((`NNG_OPT_RECVTIMEO`)):: +(((receive, timeout))) +(((timeout, receive))) +(`<>`) +This is the socket receive timeout in milliseconds. +When no message is available for receiving at the socket for this period of +time, receive operations will fail with a return value of `NNG_ETIMEDOUT`. + +[[NNG_OPT_REMADDR]] +((`NNG_OPT_REMADDR`)):: +(`<>`) +This read-only option may be used on dialers and connected pipes, and +represents the address of a remote peer. +Not all transports support this option. + +[[NNG_OPT_SENDBUF]] +((`NNG_OPT_SENDBUF`)):: +(((send, buffer))) +(((buffer, send))) +(`int`) +This is the depth of the socket send buffer as a number of messages. +Messages sent by an application may be buffered by the socket until a +transport is ready to accept them for delivery. +This value must be an integer between 0 and 8192, inclusive. + +NOTE: Not all protocols support buffering sent messages; +generally multicast protocols like <> will +simply discard messages when they cannot be delivered immediately. + +[[NNG_OPT_SENDFD]] +((`NNG_OPT_SENDFD`)):: +(((poll))) +(((select))) +(((send, polling))) +(`int`) +This read-only option is used to obtain an integer file descriptor suitable +for use in `poll()`, `select()`, (or on Windows systems `WSApoll()`) and +similar functions. +This descriptor will be *readable* when the socket is able to accept a +message for sending without blocking. +When the socket is no longer able to accept such messages without blocking, +the descriptor will *not* be readable. + +IMPORTANT: Appplications should never attempt to read or write to the +returned file descriptor. +Furthermore, applications should not attempt to use the actual socket (of +type `<>`) with polling functions, +since it is merely an internal +identifier and will not necessarily referency any operting system object or +handle. + +TIP: While this option may help applications integrate into existing polling +loops, it is more efficient, and often easier, to use the asynchronous I/O +objects instead. See `<>`. + +[[NNG_OPT_SENDTIMEO]] +((`NNG_OPT_SENDTIMEO`)):: +(((send, timeout))) +(((timeout, send))) +(`<>`) +This is the socket send timeout in milliseconds. +When a message cannot be queued for delivery by the socket for this period of +time (such as if send buffers are full), the operation will fail with a +return value of `NNG_ETIMEDOUT`. + +[[NNG_OPT_SOCKNAME]] +((`NNG_OPT_SOCKNAME`)):: +(((name, socket))) +(string) +This the socket name. +By default this is a string corresponding to the value of the socket. +The string must fit within 64-bytes, including the terminating +`NUL` byte, but it can be changed for other application uses. + +[[NNG_OPT_MAXTTL]] +((`NNG_OPT_MAXTTL`)):: +(`int`) +(((time-to-live))) +This is the maximum number of "`hops`" a message may traverse (see +`<>`). +The intention here is to prevent ((forwarding loops)) in device chains. + +// ((`NNG_OPT_REMADDR`)):: Endpoint specific, readonly +// ((`NNG_OPT_LOCADDR`)):: Endpoint specific, readonly + +[[NNG_OPT_URL]] +((`NNG_OPT_URL`)):: +(((URI))) +(((URL))) +(string) +This read-only option is used to obtain the URL with which a listener +or dialer was configured. +Accordingly it can only be used with dialers, listeners, and pipes. + +NOTE: Some transports will canonify URLs before returning them to the +application. + +== SEE ALSO +[.text-left] +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_setopt.adoc b/docs/man/nng_setopt.adoc new file mode 100644 index 00000000..482d8c2b --- /dev/null +++ b/docs/man/nng_setopt.adoc @@ -0,0 +1,116 @@ += nng_setopt(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_setopt - set socket option + +== SYNOPSIS + +[source, c] +----------- +#include + +int nng_setopt(nng_socket s, const char *opt, const void *val, size_t valsz); + +int nng_setopt_int(nng_socket s, const char *opt, int ival); + +int nng_setopt_ms(nng_socket s, const char *opt, nng_duration dur); + +int nng_setopt_ptr(nng_socket s, const char *opt, void *ptr); + +int nng_setopt_size(nng_socket s, const char *opt, size_t z); + +int nng_setopt_string(nng_socket s, const char *opt, const char *str); + +int nng_setopt_uint64(nng_socket s, const char *opt, uint64_t u64); +----------- + +== DESCRIPTION + +The `((nng_setopt))()` functions are used to configure options for +the socket _s_. +The actual options that may be configured in this way vary, and are +specified by _opt_. +A number of them are documented in <>. + +Additionally some transport-specific and protocol-specific options are +documented with the transports and protocols themselves. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +TIP: Generally, it will be easier to use one of the typed versions +of this function. + +NOTE: No validation that the option is actually of the associated +type is performed, so the caller must take care to use the *correct* typed form. + +`nng_setopt()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. + +`nng_setopt_int()`:: +This function is for options which take an integer (`int`) or boolean (`bool`). +The _ival_ is passed to the option. +For booleans pass either 0 (`false`) or 1 (`true`). + +`nng_setopt_ms()`:: +This function is used to configure time durations (such as timeouts). +The duration _dur_ is an integer number of milliseconds. +(The special value ((`NNG_DUR_INFINITE`)) means an infinite amount of time.) + +`nng_setopt_ptr()`:: +This function is used to pass a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed by other functions. +For example, TLS configuration objects +(<>) can be passed this way. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +`nng_setopt_size()`:: +This function is used to configure a size, _z_, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_setopt_string()`:: +This function is used to pass configure a string, _str_. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. +(Other constraints may apply as well, see the documentation for each option +for details.) + +`nng_setopt_uint64()`:: +This function is used to configure a 64-bit unsigned value, _u64_. +This is typically used for options related to identifiers, network numbers, +and similar. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. +`NNG_EINVAL`:: The value being passed is invalid. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EREADONLY`:: The option _opt_ is read-only. +`NNG_ESTATE`:: The socket is in an inappropriate state for setting this option. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_zerotier.adoc b/docs/man/nng_zerotier.adoc index 06f89566..b77b8b8c 100644 --- a/docs/man/nng_zerotier.adoc +++ b/docs/man/nng_zerotier.adoc @@ -24,6 +24,7 @@ int nng_zt_register(void); == DESCRIPTION +(((ZeroTier))) The _nng_zerotier_ transport provides communication support for _nng_ applications over a http://www.zerotier.com[ZeroTier] network, using a Virtual Layer 2 packet facility. @@ -31,7 +32,7 @@ using a Virtual Layer 2 packet facility. IMPORTANT: This transport is very experimental. To utilize it at present, the library must be built with support, and the ZeroTierOne `dev` branch must be included; this will require -linking against a suitable `libzerotiercore` static library. +linking against a suitable ((`libzerotiercore`)) static library. IMPORTANT: The `libzerotiercore` library at present is covered under different license terms than the rest of _nng_. Please be careful to review @@ -63,6 +64,7 @@ cannot be initialized for any reason. === URI Format +(((URI, `zt://`))) This transport uses URIs using the scheme `zt://`, followed by a node number (ten hexadecimal digits) followed by a `.` delimited, and then a network address (sixteen hexadecimal digits), followed by a colon (`.`) @@ -79,6 +81,9 @@ selected port number using the `nng_listener_getopt` function. === Socket Address +(((address, socket, zerotier))) +(((`NNG_AF_ZT`))) +(((`nng_sockaddr_zt`))) When using an `nng_sockaddr` structure, the actual structure is of type `struct nng_sockaddr_zt`. This type has the following definition: @@ -116,31 +121,31 @@ It is possible for a single application to join multiple networks using the same node, or using separate nodes. === Network Status - +(((status, zerotier network))) A ZeroTier node can be in one of the following states, which can be obtained with the `NNG_OPT_ZT_NETWORK_STATUS` option: -`NNG_ZT_STATUS_UP`:: +((`NNG_ZT_STATUS_UP`)):: The ZeroTier network is up. This is the only state where it is possible to communicate with peers, and the only state where the network name (`NNG_OPT_ZT_NETWORK_NAME`) is available. -`NNG_ZT_STATUS_CONFIG`:: +((`NNG_ZT_STATUS_CONFIG`)):: The ZeroTier node is still configuring, network services are not available. -`NNG_ZT_STATUS_DENIED`:: +((`NNG_ZT_STATUS_DENIED`)):: The node does not have permission to join the ZeroTier network. -`NNG_ZT_STATUS_NOTFOUND`:: +((`NNG_ZT_STATUS_NOTFOUND`)):: The ZeroTier network is not found. -`NNG_ZT_STATUS_ERROR`:: +((`NNG_ZT_STATUS_ERROR`)):: Some other ZeroTier error has occurred; the network is not available. -`NNG_ZT_STATUS_OBSOLETE`:: +((`NNG_ZT_STATUS_OBSOLETE`)):: The node is running obsolete software; the network is not available. -`NNG_ZT_STATUS_UNKNOWN`:: +((`NNG_ZT_STATUS_UNKNOWN`)):: The network is in an unknown state. This should not happen, as it indicates that the ZeroTier software is reporting an unexpected status. The network is most likely not available. @@ -149,8 +154,7 @@ The network is most likely not available. The following transport options are available: -`NNG_OPT_ZT_HOME`:: - +((`NNG_OPT_ZT_HOME`)):: This is a string representing the "home directory", where the transport can store (and reuse) persistent state, such as key materials, node identity, and federation membership. This option must be set before the @@ -163,76 +167,68 @@ dialers, or listeners, then separate nodes will be created. It is perfectly valid for an application to have multiple node identities in this fashion. -`NNG_OPT_ZT_NWID`:: - +((`NNG_OPT_ZT_NWID`)):: This is a read-only option for listeners, dialers, and pipes, and provides a `uint64_t` in native byte order representing the 64-bit ZeroTier network number. -`NNG_OPT_ZT_NODE`:: - +((`NNG_OPT_ZT_NODE`)):: This is a read-only option for listeners, dialers, and pipes, and provides a `uint64_t` in native byte order representing the ZeroTier 40-bit node address. -`NNG_OPT_ZT_NETWORK_STATUS`:: - +((`NNG_OPT_ZT_NETWORK_STATUS`)):: + (((status, zerotier network))) This is a read-only integer, representing the ZeroTier network status. See <> for an explanation of this option. -`NNG_OPT_ZT_NETWORK_NAME`:: - +((`NNG_OPT_ZT_NETWORK_NAME`)):: + (((name, zerotier network))) This is a read-only ASCIIZ string containing the name of the network as established by the ZeroTier network administrator. -`NNG_OPT_ZT_CONN_TIME`:: - +((`NNG_OPT_ZT_CONN_TIME`)):: The time to wait between sending connection attempts. This is an `nng_duration` (msec), and is only used with dialers. The default is 500 msec. -`NNG_OPT_ZT_CONN_TRIES`:: - +((`NNG_OPT_ZT_CONN_TRIES`)):: The maximum number (`int`) of attempts to try to establish a connection before reporting a timeout, and is only used with dialers. The default is 240, which results in a 2 minute timeout if `NNG_OPT_ZT_CONN_TIME` is at it's default of 500. If the value is set to 0, then the connection attempts will keep retrying forever. -`NNG_OPT_ZT_PING_TIME`:: - +((`NNG_OPT_ZT_PING_TIME`)):: If no traffic has been received from the ZeroTier peer after this period of time, then a "ping" message is sent to check if the peer is still alive. This is an `nng_duration` (msec). -`NNG_OPT_ZT_PING_TRIES`:: - +((`NNG_OPT_ZT_PING_TRIES`)):: If this number (`int`) of consecutive "ping" requests are sent to the peer with no response (and no other intervening traffic), then the peer is assumed to be dead and the connection is closed. Note that if any traffic is received from the peer, then the underlying counter is reset to zero. -`NNG_OPT_ZT_MTU`:: - +((`NNG_OPT_ZT_MTU`)):: This is a read-only size (`size_t`) representing the ZeroTier virtual network MTU; this is the Virtual Layer 2 MTU. The headers used by this transport and the protocols consume some of this for each message sent over the network. (The transport uses 20-bytes of this, and each protocol may consume additional space, typically not more than 16-bytes.) -`NNG_OPT_ZT_ORBIT`:: - +((`NNG_OPT_ZT_ORBIT`)):: This is a write-only option that takes an array of two `uint64_t` values, indicating the ID of a ZeroTier "moon", and the node ID of the root server for that moon. (The ID may be zero if the moon ID is the same as it's root server ID, which is conventional.) -`NNG_OPT_ZT_DEORBIT`:: - +((`NNG_OPT_ZT_DEORBIT`)):: This write-only option takes a single `uint64_t` indicating the moon ID to "deorbit". If the node is not already orbiting the moon, then this has no effect. == SEE ALSO +[.text-left] <> diff --git a/docs/man/nngcat.adoc b/docs/man/nngcat.adoc index 4b5de355..18b4c359 100644 --- a/docs/man/nngcat.adoc +++ b/docs/man/nngcat.adoc @@ -23,7 +23,7 @@ nngcat - command line access to Scalabity Protocols == DESCRIPTION -The _nngcat_ utility provides command line access to the Scalability +The ((_nngcat_)) utility provides command line access to the Scalability Protocols, making it possible to write shell scripts that interact with other peers in a Scalability Protocols topology, by both sending and receiving messages. @@ -61,7 +61,8 @@ each option must be presented as a separate argument to the program. *-q, --silent*:: Select silent operation. *--compat*:: - Compatible mode. This cause _nngcat_ to behave more like the legacy + Compatible mode. (((compatible mode))) + This cause _nngcat_ to behave more like the legacy _nanocat_ application. In this mode connections are made asynchronously, and the *--pair* option selects version 0 of the <> protocol instead of version 1. @@ -173,14 +174,16 @@ options can only be specified when using a protocol that receives messages. `raw`::: Raw output, every byte received is sent to standard output. `ascii`::: - ASCII safe, printable ASCII is emitted verbatim, with other bytes + ((ASCII)) safe, printable ASCII is emitted verbatim, with other bytes substituted with `.` (period). `quoted`::: - Messages are printed as quoted strings, using C language conventions. + Messages are printed as ((quoted)) strings, using C language conventions. `hex`::: - Messages are printed as quoted strings, with every byte appearing as - an escaped hexadecimal value, such as `\x2E`. + (((hex))) Messages are printed as quoted strings, with every byte appearing + as an escaped hexadecimal value, such as `\x2E`. `msgpack`::: + (((msgpack))) + (((MessagePack))) Messages are emitted as https://msgpack.org[MessagePack] "bin format" (byte arrays). @@ -280,6 +283,7 @@ $ nngcat --sub --dial=${addr} --quoted & == SEE ALSO +[.text-left] <>, <>, <>, diff --git a/docs/man/publish.sh b/docs/man/publish.sh index 63a1a26c..57710c67 100755 --- a/docs/man/publish.sh +++ b/docs/man/publish.sh @@ -194,6 +194,7 @@ EOF typeset -A titles titles[1]="Utilities and Programs" titles[3]="Library Functions" +titles[5]="Macros and Types" titles[7]="Protocols and Transports" for S in $(echo ${!pages[@]} | sort ) -- cgit v1.2.3-70-g09d2