diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/nng_close.adoc | 78 | ||||
| -rw-r--r-- | docs/nng_inproc.adoc | 103 | ||||
| -rw-r--r-- | docs/nng_zerotier.adoc | 40 |
3 files changed, 203 insertions, 18 deletions
diff --git a/docs/nng_close.adoc b/docs/nng_close.adoc new file mode 100644 index 00000000..b767b2ef --- /dev/null +++ b/docs/nng_close.adoc @@ -0,0 +1,78 @@ +nng_close(3) +============ +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:icons: font +:source-highlighter: pygments +:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \ + Copyright 2017 Capitar IT Group BV <info@capitar.com> \ + This software 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_close - close a socket + +SYNOPSIS +-------- + +[source, c] +----------- +#include <nng/nng.h> + +int +nng_close (int s); +----------- + + +DESCRIPTION +----------- + +The `nng_close()` function closes the supplied socket, 's'. Messages +that have been submitted for sending may be flushed or delivered, +depending upon the transport and the setting of the `NNG_OPT_LINGER` +option. + +Further attempts to use the socket after this call returns will result +in `NNG_EBADF`. Threads waiting for operations on the socket when this +call is executed may also return with an `NNG_EBADF` result. + + +RETURN VALUES +------------- + +This function returns 0 on success, and non-zero otherwise. + + +ERRORS +------ + +`NNG_EBADF`:: The socket is already closed or was never opened. + + +AUTHORS +------- + +link:mailto:garrett@damore.org[Garrett D'Amore] + + +SEE ALSO +-------- + +<<nng_setopt#,nng_setopt(3)>> +<<nng_strerror#,nng_strerror(3)>> +<<nng#,nng(7)>> + + +COPYRIGHT +--------- + +Copyright 2017 mailto:garrett@damore.org[Garrett D'Amore] + +Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/LICENSE.txt[MIT License]. diff --git a/docs/nng_inproc.adoc b/docs/nng_inproc.adoc new file mode 100644 index 00000000..7a49fa76 --- /dev/null +++ b/docs/nng_inproc.adoc @@ -0,0 +1,103 @@ +nng_inproc(7) +============= +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 7 +:icons: font +:source-highlighter: pygments +:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \ + Copyright 2017 Capitar IT Group BV <info@capitar.com> \ + This software 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_inproc - intra-process transport for nng + +SYNOPSIS +-------- + +[source,c] +---------- +#include <nng/transport/inproc/inproc.h> + +int +nng_inproc_register(void); +---------- + +DESCRIPTION +----------- + +The _nng_inproc_ transport provides communication support between +_nng_ sockets within the same process. This may be used as an alternative +to slower transports when data must be moved within the same process. + +This transport tries hard to avoid copying data, and thus is very +light-weight. + +Registration +~~~~~~~~~~~~ + +The _inproc_ transport is generally built-in to the _nng_ core, so +no extra steps to use it should be necessary. + +URI Format +~~~~~~~~~~ + +This transport uses URIs using the scheme `inproc://`, followed by +an arbitrary string of text, terminated by a `NUL` byte. The +entire URI must be less than `NNG_MAXADDRLEN` bytes long, including +the terminating `NUL`. + +Multiple URIs can be used within the +same application, and they will not interfere with one another. + +Two applications may also use the same URI without interfering with each +other, and they will be unable to communicate with each other using +that URI. + +Socket Address +~~~~~~~~~~~~~~ + +When using an `nng_sockaddr` structure, the actual structure is of type +`struct nng_sockaddr_inproc`. This type has the following definition: + +[source,c] +-------- +#define NNG_AF_INPROC 1 +#define NNG_MAXADDRLEN 128 + +struct nng_sockaddr_inproc { + uint16_t sa_family; // must be NNG_AF_INPROC + uint32_t sa_path[NNG_MAXADDRLEN]; // arbitrary "path" +} +-------- + +The `sa_family` member will have the value `NNG_AF_INPROC` (1). +The `sa_path` member is an ASCIIZ string, and may contain any charaters, +terminated by a `NUL` byte. + +Transport Options +~~~~~~~~~~~~~~~~~ + +The _inproc_ transport has no special options. + +AUTHORS +------- +link:mailto:garrett@damore.org[Garrett D'Amore] + +SEE ALSO +-------- +<<nng.adoc#,nng(7)>> + +COPYRIGHT +--------- + +Copyright 2017 mailto:garrett@damore.org[Garrett D'Amore] + +Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/LICENSE.txt[MIT License]. diff --git a/docs/nng_zerotier.adoc b/docs/nng_zerotier.adoc index c8a658ef..6fa87737 100644 --- a/docs/nng_zerotier.adoc +++ b/docs/nng_zerotier.adoc @@ -20,9 +20,13 @@ nng_zerotier - ZeroTier transport for nng SYNOPSIS -------- -*#include <nn/transports/zt.h>* +[source,c] +---------- +#include <nng/transport/zerotier/zerotier.h> -*int nng_zt_register(void);* +int +nng_zt_register(void); +---------- DESCRIPTION ----------- @@ -118,7 +122,7 @@ Transport Options 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 @@ -132,19 +136,19 @@ 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`:: This is a read-ony integer, representing the ZeroTier network status. Valid values for this are: @@ -152,39 +156,39 @@ in this fashion. [cols="1,2"] |=== -| *nng_zt_network_status_configuring* +| `nng_zt_network_status_configuring` | The ZeroTier node is still configuring, network services are not available. -| *nng_zt_network_status_ok* +| `nng_zt_network_status_ok` | The ZeroTier network is up. -| *nng_zt_network_status_denied* +| `nng_zt_network_status_denied` | The node does not have permission to join the ZeroTier network. -| *nng_zt_network_status_notfound* +| `nng_zt_network_status_notfound` | The ZeroTier network is not found. -| *nng_zt_network_status_error* +| `nng_zt_network_status_error` | Some other ZeroTier error has occurred; the network is not available. -| *nng_zt_network_status_obsolete* +| `nng_zt_network_status_obsolete` | The node is running obsolete software; the network is not available. |=== -*NNG_OPT_ZT_NETWORK_NAME*:: +`NNG_OPT_ZT_NETWORK_NAME`:: This is a read-only ASCIIZ string containing the name of the network as established by the ZeroTier network administrator. -*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_COUNT*:: +`NNG_OPT_ZT_PING_COUNT`:: If this number (`int`) of consecutive "ping" requests are sent to the peer with no response (and no other intervening traffic), then the @@ -192,7 +196,7 @@ in this fashion. 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 @@ -200,14 +204,14 @@ in this fashion. 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 |