Untitled

From 2c1d138c774336e846a70f9e5c18f9c23ebb6ff2 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 30 Dec 2017 19:18:49 -0800 Subject: man page updates for 0.2.0 --- man/v0.2.0/README.html | 456 +++++++++++++++++++++ man/v0.2.0/libnng.html | 793 +++++++++++++++++++++++++++++++++++++ man/v0.2.0/nng.html | 632 +++++++++++++++++++++++++++++ man/v0.2.0/nng_bus.html | 632 +++++++++++++++++++++++++++++ man/v0.2.0/nng_close.html | 594 ++++++++++++++++++++++++++++ man/v0.2.0/nng_inproc.html | 638 ++++++++++++++++++++++++++++++ man/v0.2.0/nng_ipc.html | 654 ++++++++++++++++++++++++++++++ man/v0.2.0/nng_pair.html | 725 ++++++++++++++++++++++++++++++++++ man/v0.2.0/nng_pub.html | 618 +++++++++++++++++++++++++++++ man/v0.2.0/nng_pull.html | 605 ++++++++++++++++++++++++++++ man/v0.2.0/nng_push.html | 623 +++++++++++++++++++++++++++++ man/v0.2.0/nng_rep.html | 643 ++++++++++++++++++++++++++++++ man/v0.2.0/nng_req.html | 693 ++++++++++++++++++++++++++++++++ man/v0.2.0/nng_respondent.html | 645 ++++++++++++++++++++++++++++++ man/v0.2.0/nng_strerror.html | 602 ++++++++++++++++++++++++++++ man/v0.2.0/nng_sub.html | 649 ++++++++++++++++++++++++++++++ man/v0.2.0/nng_surveyor.html | 663 +++++++++++++++++++++++++++++++ man/v0.2.0/nng_tcp.html | 696 ++++++++++++++++++++++++++++++++ man/v0.2.0/nng_tls.html | 876 +++++++++++++++++++++++++++++++++++++++++ man/v0.2.0/nng_ws.html | 752 +++++++++++++++++++++++++++++++++++ man/v0.2.0/nng_zerotier.html | 809 +++++++++++++++++++++++++++++++++++++ 21 files changed, 13998 insertions(+) create mode 100644 man/v0.2.0/README.html create mode 100644 man/v0.2.0/libnng.html create mode 100644 man/v0.2.0/nng.html create mode 100644 man/v0.2.0/nng_bus.html create mode 100644 man/v0.2.0/nng_close.html create mode 100644 man/v0.2.0/nng_inproc.html create mode 100644 man/v0.2.0/nng_ipc.html create mode 100644 man/v0.2.0/nng_pair.html create mode 100644 man/v0.2.0/nng_pub.html create mode 100644 man/v0.2.0/nng_pull.html create mode 100644 man/v0.2.0/nng_push.html create mode 100644 man/v0.2.0/nng_rep.html create mode 100644 man/v0.2.0/nng_req.html create mode 100644 man/v0.2.0/nng_respondent.html create mode 100644 man/v0.2.0/nng_strerror.html create mode 100644 man/v0.2.0/nng_sub.html create mode 100644 man/v0.2.0/nng_surveyor.html create mode 100644 man/v0.2.0/nng_tcp.html create mode 100644 man/v0.2.0/nng_tls.html create mode 100644 man/v0.2.0/nng_ws.html create mode 100644 man/v0.2.0/nng_zerotier.html diff --git a/man/v0.2.0/README.html b/man/v0.2.0/README.html new file mode 100644 index 00000000..9cf429c9 --- /dev/null +++ b/man/v0.2.0/README.html @@ -0,0 +1,456 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + +Untitled + + + + + +

This contains the nng documentation for API users.

The documentation is written in asciidoc in the form of man pages. It is +automatically formatted for display on the website.

It is possible to emit TROFF sources for use by the UNIX man page, and HTML +for online viewing. asciidoctor supports PDF and EPUB formats via plugins, +so there are still more options available.

+ + + diff --git a/man/v0.2.0/libnng.html b/man/v0.2.0/libnng.html new file mode 100644 index 00000000..a0f3ccbb --- /dev/null +++ b/man/v0.2.0/libnng.html @@ -0,0 +1,793 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +libnng(3) + + + + + + +

SYNOPSIS

cc [flags] files -lnng [libraries]

DESCRIPTION

The nng(7) library provides a common messaging framework +intended to solve common communication problems in distributed applications.

It provides a C language API.

Common Functions

The following common functions exist in libnng.

+ ++++ + + + + + + + + + + + + + + + + + + +

nng_alloc(3)

allocate memory

nng_dial(3)

create and start a dialer

nng_free(3)

free memory

nng_strerror(3)

return an error description

Socket Functions

The following functions operate on sockets.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

nng_close(3)

close a socket

nng_closeall(3)

close all open sockets

nng_dial(3)

create and start a dialer

nng_getopt(3)

get a socket option

nng_listen(3)

create and start a listener

nng_recv(3)

receive data

nng_send(3)

send data

nng_setopt(3)

set a socket option

Message Functions

Applications desiring to use the richest part of libnng will want to +use the message API, where a message structure is passed between functions. +This API provides the most power support for zero-copy.

Messages are divided into a header and body, where the body generally carries +user-payload and the header carries protocol specific header information. +Most applications will only interact with the body.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

nng_msg_alloc(3)

allocate a message

nng_msg_body(3)

return the message body

nng_msg_free(3)

free a message

nng_msg_header(3)

return the message header

nng_msg_header_len(3)

return the message header length

nng_msg_len(3)

return the message body length

nng_msg_realloc(3)

reallocate a message

nng_recvmsg(3)

receive a message

nng_sendmsg(3)

send a message

Asynchronous Operations

Most applications will interact with nng synchronously; that is that +functions such as nng_send() will block the calling +thread until the operation has completed.

+ + + + + +

+ +	+Synchronous operations which send messages may return before the +message has actually been received, or even transmitted. Instead, These +functions return as soon as the message was successfully queued for +delivery. +

Asynchronous operations behave differently. These operations are +initiated by the calling thread, but control returns immediately to +the calling thread. When the operation is subsequently completed (regardless +of whether this was successful or not), then a user supplied function +("callback") is executed.

A context structure, called an aio, is allocated and associated for +each asynchronous operation. Only a single asynchronous operation may +be associated with an aio at any time.

The following functions are used in the asynchronous model:

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

nng_aio_alloc(3)

allocate asynchronous I/O context

nng_aio_cancel(3)

cancel asynchronous I/O operation

nng_aio_free(3)

free asynchronous I/O context

nng_aio_get_msg(3)

get message from an asynchronous receive

nng_aio_result(3)

return result from asynchronous operation

nng_aio_stop(3)

stop asynchronous I/O operation

nng_aio_wait(3)

wait for an asynchronous I/O operation

nng_aio_set_msg(3)

set message for an asynchronous send

nng_aio_set_timeout(3)

set timeout for an asynchronous send

nng_recv_aio(3)

receive a message asynchronously

nng_send_aio(3)

send a message asynchronously

Protocols

The following functions are used to construct a socket with a specific +protocol:

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

open a bus socket

open a pair socket

open a pub socket

open a rep socket

open a req socket

nng_respondent_open(3)

open a respondent socket

nng_sub_open(3)

open a sub socket

nng_surveyor_open(3)

open a surveyor socket

Transports

The following functions are used to register a transport for use.

+ ++++ + + + + + + + + + + + + + + + + + + +

nng_inproc_register(3)

nng_ipc_register(3)

nng_tcp_register(3)

nng_zerotier_register(3)

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng.html b/man/v0.2.0/nng.html new file mode 100644 index 00000000..55f3f4c5 --- /dev/null +++ b/man/v0.2.0/nng.html @@ -0,0 +1,632 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng(7) + + + + + + +

SYNOPSIS

cc [flags] files -lnng [libraries]

DESCRIPTION

The nng library provides a common messaging framework intended to +solve common communication problems in distributed applications. +It offers a number of protocols, and also a number of transports.

The protocols implement the semantics associated with particular +communications scenarios, such as RPC style services, service discovery, +publish/subscribe, and so forth.

The transports provide support for underlying transport methods, such +as TCP, IPC, websockets, and so forth.

The nng library is designed to permit easy creation of new transports and, +to a lesser extent, new protocols.

The nng library is wire compatible with the SP protocols described in +the nanomsg project; projects using +libnanomsg can inter-operate with +nng as well as other conforming implementations. (One such implementation +is mangos.) Applications using nng +which wish to communicate with older libraries must ensure that they only +use protocols or transports offered by the earlier library.

The nng library also offers a compatible API, permitting legacy code to +be recompiled or relinked against nng. When doing this, support for +certain enhancements or features will likely be absent, requiring the +application developer to use the new-style API.

The nng library is implemented in pure C; if you need bindings for +other languages please check the website.

Protocols

+
nng_bus(7) - Bus protocol
+
+
nng_pair(7) - Pair protocol
+
+
nng_pub(7) - Publisher side of publish/subscribe protocol
+
+
nng_sub(7) - Subscriber side of publish/subscribe protocol
+
+
nng_rep(7) - Reply side of request/reply protocol
+
+
nng_req(7) - Request side of request/reply protocol
+
+
nng_respondent(7) - Respondent side of survey protocol
+
+
nng_surveyor(7) - Surveyor side of survey protocol
+

Transports

+
nng_inproc(7) - Intra-process transport
+
+
nng_ipc(7) - Inter-process transport
+
+
nng_tls(7) - TLSv1.2 over TCP transport
+
+
nng_tcp(7) - TCP (and TCPv6) transport
+
+
nng_zerotier(7) - ZeroTier transport
+

Conceptual Overview

nng presents a socket view of networking. The sockets are constructed +using protocol-specific functions, as a given socket implements precisely +one nng protocol.

Each socket can be used to send and receive messages (if the protocol) +supports it, and implements the appropriate protocol semantics. For +example, nng_sub(7) sockets automatically filter incoming +messages to discard those for topics that have not been subscribed.

nng sockets are message oriented, so that messages are either delivered +wholly, or not at all. Partial delivery is not possible. Furthermore, +nng does not provide any other delivery or ordering guarantees; +messages may be dropped or reordered. (Some protocols, such as +nng_req(7) may offer stronger guarantees by +performing their own retry and validation schemes.)

Each socket can have zero, one, or many "endpoints", which are either +listeners or dialers. (A given socket may freely choose whether it uses +listeners, dialers, or both.) These "endpoints" provide access to +underlying transports, such as TCP, etc.

Each endpoint is associated with a URL, which is a service address. For +dialers, this will be the service address that will be contacted, whereas +for listeners this is where the listener will bind and watch for new +connections.

Endpoints do not themselves transport data. They are instead responsible +for the creation of pipes, which can be thought of as message-oriented, +connected, streams. Pipes frequently correspond to a single underlying +byte stream — for example both IPC and TCP transports implement their +pipes using a 1:1 relationship with a connected socket.

Endpoints create pipes as needed. Listeners will create them when a new +client connection request arrives, and dialers will generally create one, +then wait for it to disconnect before reconnecting.

Most applications should not have to worry about endpoints or pipes at +all; the socket abstraction should provide all the functionality needed +other than in a few specific circumstances.

API

The library API is documented at libnng(3).

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_bus.html b/man/v0.2.0/nng_bus.html new file mode 100644 index 00000000..e8ab97fd --- /dev/null +++ b/man/v0.2.0/nng_bus.html @@ -0,0 +1,632 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_bus(7) + + + + + + + +

SYNOPSIS

#include <nng/protocol/bus0/bus.h>
+
+int nng_bus0_open(nng_socket *s);

DESCRIPTION

The nng_bus protocol provides for building mesh networks where +every peer is connected to every other peer. In this protocol, +each message sent by a node is sent to every one of its directly +connected peers.

+ + + + + +

+ +	+Messages are only sent to directly connected peers. This means +that in the event that a peer is connected indirectly, it will not +receive messages. When using this protocol to build mesh networks, it +is therefore important that a fully-connected mesh network be +constructed. +

All message delivery in this pattern is best-effort, which means that +peers may not receive messages. Furthermore, delivery may occur to some, +all, or none of the directly connected peers. (Messages are not delivered +when peer nodes are unable to receive.) Hence, send operations will never +block; instead if the message cannot be delivered for any reason it is +discarded.

+ + + + + +

+ +	+In order to minimize the likelihood of message loss, this protocol +should not be used for high throughput communications. Furthermore, the +more traffic in aggregate that occurs across the topology, the more +likely that message loss is to occur. +

Socket Operations

The nng_bus0_open() call creates a bus socket. This socket +may be used to send and receive messages. Sending messages will +attempt to deliver to each directly connected peer.

Protocol Versions

Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.)

Protocol Options

The nng_bus protocol has no protocol-specific options.

Protocol Headers

The nng_bus protocol has no protocol-specific headers.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_close.html b/man/v0.2.0/nng_close.html new file mode 100644 index 00000000..55b46eaf --- /dev/null +++ b/man/v0.2.0/nng_close.html @@ -0,0 +1,594 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_close(3) + + + + + + + +

SYNOPSIS

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

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_inproc.html b/man/v0.2.0/nng_inproc.html new file mode 100644 index 00000000..b292b300 --- /dev/null +++ b/man/v0.2.0/nng_inproc.html @@ -0,0 +1,638 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_inproc(7) + + + + + + + +

SYNOPSIS

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

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:

#define NNG_AF_INPROC 1 (1)
+#define NNG_MAXADDRLEN 128
+
+typedef nng_sockaddr_inproc {
+    (2)
+    uint16_t sa_family;                  // must be NNG_AF_INPROC
+    char     sa_path[NNG_MAXADDRLEN];    // arbitrary "path"
+    //
+}

+ + + + + + + + + +

1	The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically.
2	Other members may be present, but only those listed here +are suitable for application use.

The sa_family member will have the value NNG_AF_INPROC. +The sa_path member is an ASCIIZ string, and may contain any characters, +terminated by a NUL byte.

Transport Options

The inproc transport has no special options.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_ipc.html b/man/v0.2.0/nng_ipc.html new file mode 100644 index 00000000..850ae690 --- /dev/null +++ b/man/v0.2.0/nng_ipc.html @@ -0,0 +1,654 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_ipc(7) + + + + + + + +

SYNOPSIS

#include <nng/transport/ipc/ipc.h>
+
+int nng_ipc_register(void);

DESCRIPTION

The nng_ipc transport provides communication support between +nng sockets within different processes on the same host. For POSIX +platforms, this is implemented using UNIX domain sockets. For Windows, +this is implemented using Windows Named Pipes. Other platforms may +have different implementation strategies.

Registration

The ipc 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 ipc://, followed by +a path name in the file system where the socket or named pipe +should be created.

+ + + + + +

+ + +On Windows, all names are prefixed by \.\pipe\ and do not +occupy the normal file system. On POSIX platforms, the path is +taken literally, and is relative to the current directory, unless +an extra leading / is provided. For example, ipc://myname refers +to the name myname in the current directory, whereas ipc:///tmp/myname +refers to myname located in /tmp. +

The entire URI must be less than NNG_MAXADDRLEN bytes long.

Socket Address

When using an nng_sockaddr structure, the actual structure is of type +nng_sockaddr_ipc. This is a struct type with the following definition:

#define NNG_AF_IPC 2 (1)
+#define NNG_MAXADDRLEN 128
+
+typedef struct {
+    // ... (2)
+    uint16_t sa_family;                 // must be NNG_AF_IPC
+    char     sa_path[NNG_MAXADDRLEN];   // arbitrary "path"
+    // ...
+} nng_sockaddr_ipc;

+ + + + + + + + + +

1	The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically.
2	Other members may be present, but only those listed here +are suitable for application use.

The sa_family member will have the value NNG_AF_IPC. +The sa_path member is an ASCIIZ string, and may contain any legal +path name (platform-dependent), terminated by a NUL byte.

Transport Options

The ipc transport has no special +options.^[1]

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+1. Options for security attributes and credentials are planned. +

+ + + diff --git a/man/v0.2.0/nng_pair.html b/man/v0.2.0/nng_pair.html new file mode 100644 index 00000000..bc9d554a --- /dev/null +++ b/man/v0.2.0/nng_pair.html @@ -0,0 +1,725 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_pair(7) + + + + + + + +

SYNOPSIS

Version 0

#include <nng/protocol/pair0/pair.h>
+
+int nng_pair0_open(nng_socket *s);

Version 1

#include <nng/protocol/pair1/pair.h>
+
+int nng_pair1_open(nng_socket *s);

DESCRIPTION

The nng_pair protocol implements a peer-to-peer pattern, where +relationships between peers are one-to-one.

Version 1 of this protocol supports an optional polyamorous mode where a +peer can maintain multiple partnerships. Using this mode requires +some additional sophistication in the application.

Socket Operations

The nng_pair_open() call creates a pair socket. Normally, this +pattern will block when attempting to send a message, if no peer is +able to receive the message.

+ + + + + +

+ +

+Even though this mode may appear to be "reliable", because back-pressure +prevents discarding messages most of the time, there are topologies involving +devices (see nng_device(3)) or raw mode sockets where +messages may be discarded. Applications that require reliable delivery +semantics should consider using nng_req(7) sockets, or +implement their own acknowledgement layer on top of pair sockets. +

In order to avoid head-of-line blocking conditions, polyamorous mode pair +sockets (version 1 only) discard messages if they are unable to deliver them +to a peer.

Protocol Versions

Version 0 is the legacy version of this protocol. It lacks any header +information, and is suitable when building simple one-to-one topologies.

+ + + + + +

+ +	+Use version 0 if you need to communicate with other implementations, +including the legacy nanomsg library or +mangos. +

Version 1 of the protocol offers improved protection against loops when +used with nng_device(3). It also offers polyamorous +mode for forming multiple partnerships on a single socket.

+ + + + + +

+ +	+Version 1 of this protocol is considered experimental at this time. +

Polyamorous Mode

Normally pair sockets are for one-to-one communication, and a given peer +will reject new connections if it already has an active connection to another +peer.

In polyamorous mode, which is only available with version 1, a socket can +support many one-to-one connections. In this mode, the application must +choose the remote peer to receive an ougoing message by setting the value +of the pipe ID on the outgoing message using +the nng_msg_set_pipe(3) function.

Most often the value of the outgoing pipe ID will be obtained from an incoming +message using the nng_msg_get_pipe(3) function, +such as when replying to an incoming message.

In order to prevent head-of-line blocking, if the peer on the given pipe +is not able to receive (or the pipe is no longer available, such as if the +peer has disconnected), then the message will be discarded with no notification +to the sender.

Protocol Options

The following protocol-specific options are available.

NNG_OPT_PAIR1_POLY

(Version 1 only). This option enables the use of polyamorous mode. +The value is read-write, and takes an integer boolean value. The default +false value (0) indicates that legacy monogamous mode should be used.

NNG_OPT_MAXTTL

(Version 1 only). Maximum time-to-live. This option is an integer value +between 0 and 255, +inclusive, and is the maximum number of "hops" that a message may +pass through until it is discarded. The default value is 8. A value +of 0 may be used to disable the loop protection, allowing an infinite +number of hops.

+ + + + + +

+ +	+Each node along a forwarding path may have it’s own value for the +maximum time-to-live, and performs its own checks before forwarding a message. +Therefore it is helpful if all nodes in the topology use the same value for +this option. +

Protocol Headers

Version 0 of the pair protocol has no protocol-specific headers.

Version 1 of the pair protocol uses a single 32-bit unsigned value. The +low-order (big-endian) byte of this value contains a "hop" count, and is +used in conjuction with the NNG_OPT_MAXTTL option to guard against +device forwarding loops. This value is initialized to 1, and incremented +each time the message is received by a new node.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_pub.html b/man/v0.2.0/nng_pub.html new file mode 100644 index 00000000..4a823295 --- /dev/null +++ b/man/v0.2.0/nng_pub.html @@ -0,0 +1,618 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_pub(7) + + + + + + + +

SYNOPSIS

#include <nng/protocol/pubsub0/pub.h>
+
+int nng_pub0_open(nng_socket *s);

DESCRIPTION

The nng_pub protocol is one half of a publisher/subscriber pattern. +In this pattern, a publisher sends data, which is broadcast to all +subscribers. The subscribing applications only see the data to which +they have subscribed.

The nng_pub protocol is the publisher side, and the +nng_sub(7) protocol is the subscriber side.

+ + + + + +

+ +	+In this implementation, the publisher delivers all messages to all +subscribers. The subscribers maintain their own subscriptions, and filter +them locally. Thus, this pattern should not be used in an attempt to +reduce bandwidth consumption. +

The topics that subscribers subscribe to is just the first part of +the message body. Applications should construct their messages +accordingly.

Socket Operations

The nng_pub0_open() call creates a publisher socket. This socket +may be used to send messages, but is unable to receive them. Attempts +to receive messages will result in NNG_ENOTSUP.

Protocol Versions

Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.)

Protocol Options

The nng_pub protocol has no protocol-specific options.

Protocol Headers

The nng_pub protocol has no protocol-specific headers.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_pull.html b/man/v0.2.0/nng_pull.html new file mode 100644 index 00000000..77bae75e --- /dev/null +++ b/man/v0.2.0/nng_pull.html @@ -0,0 +1,605 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_pull(7) + + + + + + + +

SYNOPSIS

#include <nng/protocol/pipeline0/pull.h>
+
+int nng_pull0_open(nng_socket *s);

DESCRIPTION

The nng_pull protocol is one half of a pipeline pattern. The other half +is the nng_push(7) protocol.

In the pipeline pattern, pushers distribute messages to pullers. +Each message sent +by a pusher will be sent to one of its peer pullers, +chosen in a round-robin fashion +from the set of connected peers available for receiving. +This property makes this pattern useful in load-balancing scenarios.

Socket Operations

The nng_pull0_open() call creates a puller socket. This socket +may be used to receive messages, but is unable to send them. Attempts +to send messages will result in NNG_ENOTSUP.

When receiving messages, the nng_pull protocol accepts messages as +they arrive from peers. If two peers both have a message ready, the +order in which messages are handled is undefined.

Protocol Versions

Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.)

Protocol Options

The nng_pull protocol has no protocol-specific options.

Protocol Headers

The nng_pull protocol has no protocol-specific headers.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_push.html b/man/v0.2.0/nng_push.html new file mode 100644 index 00000000..b174c04f --- /dev/null +++ b/man/v0.2.0/nng_push.html @@ -0,0 +1,623 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_push(7) + + + + + + + +

SYNOPSIS

#include <nng/protocol/pipeline0/push.h>
+
+int nng_push0_open(nng_socket *s);

DESCRIPTION

The nng_push protocol is one half of a pipeline pattern. The +other side is the nng_pull(7) protocol.

Socket Operations

The nng_push0_open() call creates a pusher socket. This socket +may be used to send messages, but is unable to receive them. Attempts +to receive messages will result in NNG_ENOTSUP.

Send operations will observe flow control (back-pressure), so that +only peers capable of accepting a message will be considered. If no +peer is available to receive a message, then the send operation will +wait until one is available, or the operation times out.

+ + + + + +

+ +

+Although the pipeline protocol honors flow control, and attempts +to avoid dropping messages, no guarantee of delivery is made. Furthermore, +as there is no capability for message acknowledgement, applications that +need reliable delivery are encouraged to consider the +nng_req(7) protocol instead. +

Protocol Versions

Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.)

Protocol Options

The nng_push protocol has no protocol-specific options.

Protocol Headers

The nng_push protocol has no protocol-specific headers.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_rep.html b/man/v0.2.0/nng_rep.html new file mode 100644 index 00000000..a0e953de --- /dev/null +++ b/man/v0.2.0/nng_rep.html @@ -0,0 +1,643 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_rep(7) + + + + + + + +

SYNOPSIS

#include <nng/protocol/reqrep0/rep.h>
+
+int nng_rep0_open(nng_socket *s);

DESCRIPTION

The nng_rep protocol is one half of a request/reply pattern. +In this pattern, a requester sends a message to one replier, who +is expected to reply. The request is resent if no reply arrives, +until a reply is received or the request times out.

+ + + + + +

+ +	+This protocol is useful in setting up RPC-like services. It +is also "reliable", in that a the requester will keep retrying until +a reply is received. +

The nng_rep protocol is the replier side, and the +nng_req(7) protocol is the requester side.

Socket Operations

The nng_rep0_open() call creates a requester socket. This socket +may be used to receive messages (requests), and then to send replies. Generally +a reply can only be sent after receiving a request. (Attempts to receive +a message will result in NNG_ESTATE if there is no outstanding request.)

Attempts to send on a socket with no outstanding requests will result +in NNG_ESTATE.

Raw mode sockets (set with NNG_OPT_RAW) ignore all these restrictions.

Protocol Versions

Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.)

Protocol Options

The following protocol-specific options are available.

NNG_OPT_MAXTTL: +
Maximum time-to-live. This option is an integer value +between 0 and 255, +inclusive, and is the maximum number of "hops" that a message may +pass through until it is discarded. The default value is 8. A value +of 0 may be used to disable the loop protection, allowing an infinite +number of hops.
+

Protocol Headers

The nng_rep protocol uses a backtrace in the header. This +form uses an array of 32-bit big-endian identifiers, where the first +element in the array +identifies the local peer identifier to which the message will next be sent. +This is a hop-by-hop header where each element in a path adds routing +information to the end when sending a request, and when replying removes +elements to obtain the next hop information. The request ID is at the +end of this header and is inserted into the header as its first element +by the originating surveyor. (Request IDs are distinguished from hops by +having their high order bit set to one. They are generated automatically +and randomly when a request is first issued.)

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_req.html b/man/v0.2.0/nng_req.html new file mode 100644 index 00000000..225462e4 --- /dev/null +++ b/man/v0.2.0/nng_req.html @@ -0,0 +1,693 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_req(7) + + + + + + + +

SYNOPSIS

#include <nng/protocol/reqrep0/req.h>
+
+int nng_req0_open(nng_socket *s);

DESCRIPTION

The nng_req protocol is one half of a request/reply pattern. +In this pattern, a requester sends a message to one replier, who +is expected to reply. The request is resent if no reply arrives, +until a reply is received or the request times out.

+ + + + + +

+ +	+This protocol is useful in setting up RPC-like services. It +is also "reliable", in that a the requester will keep retrying until +a reply is received. +

+ + + + + +

+ +	+Because requests are resent, it is important that they be idempotent +to ensure predictable and repeatable behavior even in the face of duplicated +requests, which can occur (for example if a reply message is lost for +some reason.) +

The requester generally only has one outstanding request at a time unless +in "raw" mode (via NNG_OPT_RAW), and it will generally attempt to spread +work requests to different peer repliers.

+ + + + + +

+ +	+This property, when combined with a device can +help provide a degree of load-balancing. +

The nng_req protocol is the requester side, and the +nng_rep(7) protocol is the replier side.

Socket Operations

The nng_req0_open() call creates a requester socket. This socket +may be used to send messages (requests), and then to receive replies. Generally +a reply can only be received after sending a request. (Attempts to receive +a message will result in NNG_ESTATE if there is no outstanding request.)

Requests may be canceled by sending a different request. This will +cause the requester to discard any reply from the earlier request, +but it will not stop a replier +from processing a request it has already received or terminate a request +that has already been placed on the wire.

Attempts to receive on a socket with no outstanding requests will result +in NNG_ESTATE.

Raw mode sockets (set with NNG_OPT_RAW) ignore all these restrictions.

Protocol Versions

Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.)

Protocol Options

The following protocol-specific options are available.

NNG_OPT_REQ_RESENDTIME: +
This read/write option is a duration (32-bit unsigned integer) representing +a relative number of milliseconds. +When a new request is started, a timer of this duration is also started. +If no reply is received before this timer expires, then the request will +be resent. (Requests are also automatically resent if the peer to whom +the original request was sent disconnects, or if a peer becomes available +while the requester is waiting for an available peer.)
+
NNG_OPT_MAXTTL: +
Maximum time-to-live. This option is an integer value +between 0 and 255, +inclusive, and is the maximum number of "hops" that a message may +pass through until it is discarded. The default value is 8. A value +of 0 may be used to disable the loop protection, allowing an infinite +number of hops.
+

Protocol Headers

The nng_req protocol uses a backtrace in the header. This +form uses an array of 32-bit big-endian identifiers, where the first +element in the array +identifies the local peer identifier to which the message will next be sent. +This is a hop-by-hop header where each element in a path adds routing +information to the end when sending a request, and when replying removes +elements to obtain the next hop information. The request ID is at the +end of this header and is inserted into the header as its first element +by the originating surveyor. (Request IDs are distinguished from hops by +having their high order bit set to one. They are generated automatically +and randomly when a request is first issued.)

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_respondent.html b/man/v0.2.0/nng_respondent.html new file mode 100644 index 00000000..3103f317 --- /dev/null +++ b/man/v0.2.0/nng_respondent.html @@ -0,0 +1,645 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_respondent(7) + + + + + + + +

SYNOPSIS

#include <nng/protocol/survey0/respondent.h>
+
+int nng_respondent0_open(nng_socket *s);

DESCRIPTION

The nng_respondent protocol is one half of a survey pattern. +In this pattern, a surveyor sends a survey, which is broadcast to all +peer respondents. The respondents then have a chance to reply (but after +not obliged to). The survey itself is a timed event, so that responses +received after the survey has finished are discarded.

+ + + + + +

+ +	+This protocol is useful in solving voting problems, such as leader +election in cluster configurations, as well as certain kinds of service +discovery problems. +

The nng_respondent protocol is the respondent side, and the +nng_surveyor(7) protocol is the surveyor side.

Socket Operations

The nng_respondent0_open() call creates a respondent socket. This socket +may be used to receive messages, and then to send replies. Generally +a reply can only be sent after receiving a survey, and generally the +reply will be sent to surveyor from whom the last survey was received.

Respondents may discard a survey by simply not replying to it.

Raw mode sockets (set with NNG_OPT_RAW) ignore all these restrictions.

Protocol Versions

Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined. An earlier and +incompatible version of the protocol was used in older pre-releases of +nanomsg, but was not released in any production +version.)

Protocol Options

The following protocol-specific options are available.

NNG_OPT_MAXTTL: +
Maximum time-to-live. This option is an integer value +between 0 and 255, +inclusive, and is the maximum number of "hops" that a message may +pass through until it is discarded. The default value is 8. A value +of 0 may be used to disable the loop protection, allowing an infinite +number of hops.
+

Protocol Headers

The nng_respondent protocol uses a backtrace in the header. This +form uses an array of 32-bit big-endian identifiers, where the first +element in the array +identifies the local peer identifier to which the message will next be sent. +This is a hop-by-hop header where each element in a path adds routing +information to the end when sending a survey, and when replying removes +elements to obtain the next hop information. The survey ID is at the +end of this header and is inserted into the header as its first element +by the originating surveyor. (Survey IDs are distinguished from hops by +having their high order bit set to one.)

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_strerror.html b/man/v0.2.0/nng_strerror.html new file mode 100644 index 00000000..6b51423a --- /dev/null +++ b/man/v0.2.0/nng_strerror.html @@ -0,0 +1,602 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_strerror(3) + + + + + + + +

SYNOPSIS

#include <nng/nng.h>
+
+const char * nng_strerror(int err);

DESCRIPTION

The nng_strerror() returns the human-readable description of the +given nng error in err.

+ + + + + +

+ +	+The returned error message is provided in US English, but in the +future locale-specific strings may be presented instead. +

+ + + + + +

+ +	+The specific strings associated with specific error messages are +subject to change. Therefore applications must not depend on the message, +but may use them verbatim when supplying information to end-users, such +as in diagnostic messages or log entries. +

RETURN VALUES

This function returns the human-readable error message, terminated +by a NUL byte.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_sub.html b/man/v0.2.0/nng_sub.html new file mode 100644 index 00000000..494b7fdb --- /dev/null +++ b/man/v0.2.0/nng_sub.html @@ -0,0 +1,649 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_sub(7) + + + + + + + +

SYNOPSIS

#include <nng/protocol/pubsub0/sub.h>
+
+int nng_sub0_open(nng_socket *s);

DESCRIPTION

The nng_sub protocol is one half of a publisher/subscriber pattern. +In this pattern, a publisher sends data, which is broadcast to all +subscribers. The subscribing applications only see the data to which +they have subscribed.

The nng_sub protocol is the subscriber side, and the +nng_pub(7) protocol is the publisher side.

+ + + + + +

+ +	+In this implementation, the publisher delivers all messages to all +subscribers. The subscribers maintain their own subscriptions, and filter +them locally. Thus, this pattern should not be used in an attempt to +reduce bandwidth consumption. +

The topics that subscribers subscribe to is just the first part of +the message body. Applications should construct their messages +accordingly.

Socket Operations

The nng_sub0_open() call creates a subscriber socket. This socket +may be used to receive messages, but is unable to send them. Attempts +to send messages will result in NNG_ENOTSUP.

Protocol Versions

Only version 0 of this protocol is supported. (At the time of writing, +no other versions of this protocol have been defined.)

Protocol Options

The following protocol-specific options are available.

NNG_OPT_SUB_SUBSCRIBE

This option registers a topic that the subscriber is interested in. +The option is write-only, and takes an array of bytes, of arbitrary size. +Each incoming message is checked against the list of subscribed topics. +If the body begins with the entire set of bytes in the topic, then the +message is accepted. If no topic matches, then the message is +discarded.

+ + + + + +

+ +	+To receive all messages, an empty topic (zero length) can be used. +

NNG_OPT_SUB_UNSUBSCRIBE

This option, also read-only, removes a topic from the subscription list. +Note that if the topic was not previously subscribed to with +NNG_OPT_SUB_SUBSCRIBE then an NNG_ENOENT error will result.

Protocol Headers

The nng_sub protocol has no protocol-specific headers.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_surveyor.html b/man/v0.2.0/nng_surveyor.html new file mode 100644 index 00000000..c9c21251 --- /dev/null +++ b/man/v0.2.0/nng_surveyor.html @@ -0,0 +1,663 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_surveyor(7) + + + + + + + +

SYNOPSIS

#include <nng/protocol/survey0/survey.h>
+
+int nng_surveyor0_open(nng_socket *s);

DESCRIPTION

The nng_surveyor protocol is one half of a survey pattern. +In this pattern, a surveyor sends a survey, which is broadcast to all +peer respondents. The respondents then have a chance to reply (but after +not obliged to). The survey itself is a timed event, so that responses +received after the survey has finished are discarded.

+ + + + + +

+ +	+This protocol is useful in solving voting problems, such as leader +election in cluster configurations, as well as certain kinds of service +discovery problems. +

The nng_surveyor protocol is the surveyor side, and the +nng_respondent(7) protocol is the respondent side.

Socket Operations

The nng_surveyor0_open() call creates a respondent socket. This socket +may be used to send messages (surveys), and then to receive replies. Generally +a reply can only be received after sending a survey. Generally a surveyor +can expect to receive at most one reply from each responder. (Messages +can be duplicated in some topologies, so there is no guarantee of this.)

Attempts to receive on a socket with no outstanding survey will result +in NNG_ESTATE. If the survey times out while the surveyor is waiting +for replies, then the result will be NNG_ETIMEDOUT.

Only one survey can be outstanding at a time; sending another survey will +cancel the prior one, and any responses from respondents from the prior +survey that arrive after this will be discarded.

Raw mode sockets (set with NNG_OPT_RAW) ignore all these restrictions.

Protocol Versions

Protocol Options

The following protocol-specific options are available.

NNG_OPT_SURVEYOR_SURVEYTIME: +
This read/write option is a duration (32-bit unsigned integer) representing +a relative number of milliseconds that following surveys will last. +When a new survey is started, a timer of this duration is also started. +Any responses arriving this time will be discarded. Attempts to receive +after the timer expires with no other surveys started will result in +NNG_ESTATE. Attempts to receive when this timer expires will result in +NNG_ETIMEDOUT.
+
NNG_OPT_MAXTTL: +
Maximum time-to-live. This option is an integer value +between 0 and 255, +inclusive, and is the maximum number of "hops" that a message may +pass through until it is discarded. The default value is 8. A value +of 0 may be used to disable the loop protection, allowing an infinite +number of hops.
+

Protocol Headers

The nng_surveyor protocol uses a backtrace in the header. This +form uses an array of 32-bit big-endian identifiers, where the first +element in the array +identifies the local peer identifier to which the message will next be sent. +This is a hop-by-hop header where each element in a path adds routing +information to the end when sending a survey, and when replying removes +elements to obtain the next hop information. The survey ID is at the +end of this header and is inserted into the header as its first element +by the originating surveyor. (Survey IDs are distinguished from hops by +having their high order bit set to one.)

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + diff --git a/man/v0.2.0/nng_tcp.html b/man/v0.2.0/nng_tcp.html new file mode 100644 index 00000000..8431444a --- /dev/null +++ b/man/v0.2.0/nng_tcp.html @@ -0,0 +1,696 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_tcp(7) + + + + + + + +

SYNOPSIS

#include <nng/transport/tcp/tcp.h>
+
+int nng_tcp_register(void);

DESCRIPTION

The nng_tcp transport provides communication support between +nng sockets across a TCP/IP network. Both IPv4 and IPv6 +are supported when the underlying platform also supports it.

Registration

The tcp 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 tcp://, followed by +an IP address or hostname, followed by a colon and finally a +TCP port number. For example, to contact port 80 on the localhost +either of the following URIs could be used: tcp://127.0.0.1:80 or +tcp://localhost:80.

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

For example, the same port 80 on the IPv6 loopback address (::1) would +be specified as tcp://[::1]:80.

+ + + + + +

+ +	+When using symbolic names, the name is resolved when the +name is first used. nng won’t become aware of changes in the +name resolution until restart, +usually.^[1] +

The special value of 0 (INADDR_ANY) can be used for a listener +to indicate that it should listen on all interfaces on the host. +A short-hand for this form is to either omit the address, or specify +the asterisk (*) character. For example, the following three +URIs are all equivalent, and could be used to listen to port 9999 +on the host:

+
tcp://0.0.0.0:9999
+
+
tcp://*:9999
+
+
tcp://:9999
+

The entire URI must be less than NNG_MAXADDRLEN bytes long.

Socket Address

When using an nng_sockaddr structure, the actual structure is either +of type nng_sockaddr_in (for IPv4) or nng_sockaddr_in6 (for IPv6). +These are struct types with the following definitions:

#define NNG_AF_INET    3 (1)
+#define NNG_AF_INET6   4
+#define NNG_MAXADDRLEN 128
+
+typedef struct {
+    // ... (2)
+    uint16_t sa_family;                 // must be NNG_AF_INET
+    uint16_t sa_port;                   // TCP port number
+    uint32_t sa_addr;
+    // ...
+} nng_sockaddr_in;
+
+typedef struct {
+    // ... (2)
+    uint16_t sa_family;                 // must be NNG_AF_INET6
+    uint16_t sa_port;                   // TCP port number
+    uint8_t  sa_addr[16];
+    // ...
+} nng_sockaddr_in6;

+ + + + + + + + + +

1	The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically.
2	Other members may be present, but only those listed here +are suitable for application use.

The sa_family member will have the value NNG_AF_INET or NNG_AF_INET6. +The sa_port and sa_addr are the TCP port number and address, both in +network byte order (most significant byte is first).

Transport Options

The tcp transport has no special +options.^[2]

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+1. This is a bug and will likely be fixed in the future. +

+2. Options for TCP keepalive, linger, and nodelay are planned. +

+ + + diff --git a/man/v0.2.0/nng_tls.html b/man/v0.2.0/nng_tls.html new file mode 100644 index 00000000..fa0fd2fc --- /dev/null +++ b/man/v0.2.0/nng_tls.html @@ -0,0 +1,876 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_tls(7) + + + + + + + +

SYNOPSIS

#include <nng/transport/tls/tls.h>
+
+int nng_tls_register(void);

DESCRIPTION

The nng_tls transport provides communication support between +nng sockets across a TCP/IP network using +TLS v1.2 on top of +TCP. Both IPv4 and IPv6 +are supported when the underlying platform also supports it.

The protocol details are documented in +TLS Mapping for Scalability Protocols.

Registration

Depending upon how the library was built, it may be necessary to +register the transport by calling nng_tls_register. This function +returns zero on success, or an nng error value if the transport +cannot be initialized for any reason.

Availability

The tls transport depends on the use of an external library. +As of this writing, mbed TLS version 2.0 +or later is required.

+ + + + + +

+ +	+Applications may need to add this library (or libraries) to +their link line, particularly when using a statically built +nng library. +

+ + + + + +

+ +	+The mbed TLS library uses different licensing terms than +nng itself; as of this writing it is offered under either +Apache License 2.0 or +GNU GPL terms. +You are responsible for understanding and adhering to the +license terms of any libraries you make use of. +

URI Format

This transport uses URIs using the scheme tls+tcp://, followed by +an IP address or hostname, followed by a colon and finally a +TCP port number. For example, to contact port 4433 on the localhost +either of the following URIs could be used: tls+tcp://127.0.0.1:4433 or +tls+tcp://localhost:4433.

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

For example, the same port 4433 on the IPv6 loopback address (::1) would +be specified as tls+tcp://[::1]:4433.

+ + + + + +

+ +	+When using symbolic names, the name is resolved when the +name is first used. nng won’t become aware of changes in the +name resolution until restart, +usually.^[1] +

+ + + + + +

+ +	+Certificate validation generally works when using names +rather than IP addresses. This transport automatically +uses the name supplied in the URL when validating the +certificate supplied by the server. +

+
tls+tcp://0.0.0.0:9999
+
+
tls+tcp://*:9999
+
+
tls+tcp://:9999
+

The entire URI must be less than NNG_MAXADDRLEN bytes long.

Socket Address

#define NNG_AF_INET    3 (1)
+#define NNG_AF_INET6   4
+#define NNG_MAXADDRLEN 128
+
+typedef struct {
+    // ... (2)
+    uint16_t sa_family;                 // must be NNG_AF_INET
+    uint16_t sa_port;                   // TCP port number
+    uint32_t sa_addr;
+    // ...
+} nng_sockaddr_in;
+
+typedef struct {
+    // ... (2)
+    uint16_t sa_family;                 // must be NNG_AF_INET6
+    uint16_t sa_port;                   // TCP port number
+    uint8_t  sa_addr[16];
+    // ...
+} nng_sockaddr_in6;

+ + + + + + + + + +

1	The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically.
2	Other members may be present, but only those listed here +are suitable for application use.

X.509 Formats

The tls transport supports certificates and key material provided +in either PEM or DER encoding. When using PEM format data, the +encoding must be at the start of the data, with no intervening +content. Furthermore, PEM encoded objects may have a terminating +NUL byte, which will be ignored if present.

Transport Options

The following transport options are available. Note that +setting these must be done before the transport is started.

NNG_OPT_TLS_CONFIG: +
This option is used to set or obtain the TLS configuration +object (type nng_tls_config *), which is passed as a pointer. +Setting this option adds a reference to the object; obtaining the +object pointer does not. (Therefore when retrieving this option, +care must be taken not to access it after the endpoint is closed.)
+

Note that configuration object is not modifiable once it has been +used in a running TLS stream.

NNG_OPT_TLS_CA_CERT

This is a write-only binay object containing a certificate +chain, consisting of one or more X.509 certificates encoded in +either PEM or DER format. These certificates are used to +validate the peer. If multiple certificates are presented, +they must be in the same format.

NNG_OPT_TLS_CRL

This is a write-only CRL (revocation list) in X.509 format, +specifying certificates which may not be used.

NNG_OPT_TLS_CERT

This is an X.509 certificate containing the peers +own public credentials. For servers, this option may be supplied +multiple times, in order to specify multiple certificates +in order to offer different algorithms. Clients can only +have a single certificate.

NNG_OPT_TLS_PRIVATE_KEY

This is an encoded private key, corresponding to the most +recently established certificate.

NNG_OPT_TLS_PRIVATE_KEY_PASSWORD

This is a string (NUL byte terminated) used to decrypt the +most recently supplied private key, if the private key +is encrypted. (If the private key is not encrypted, then +this option need not be supplied.)

NNG_OPT_TLS_AUTH_MODE

This is a write only integer, indicating whether the +peer should be authenticated. It can take one of the +following values:

+ ++++ + + + + + + + + + + + + + + +

nng_tls_auth_mode_none

No authentication of the peer is performed.

nng_tls_auth_mode_optional

The peer certificate is checked if presented, but is not required to be valid or present.

nng_tls_auth_mode_required

The peer certificate must be present and valid.

The default is nng_tls_auth_mode_required for +clients (meaning the server must present a valid +certificate) and nng_tls_auth_mode_none for +servers (meaning any client may connect).

+ + + + + +

+ +	+For TLS client authentication, set this to +`nng_auth_mode_required` and set the value +of `NNG_OPT_TLS_CA_CERT` to a certificate corresponding +to your own Certificate Authority. +

NNG_OPT_TLS_AUTH_VERIFIED

This is a read-only boolean option available only for +pipes, indicating whether the peer certificate was +valdiated or not. This is only set when the pipe +has completed the handshake with the peer (which always +occurs before exchanging data), and will only be set +if the NNG_OPT_TLS_AUTH_MODE option is set to +nng_tls_auth_mode_optional or nng_tls_auth_mode_required.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+1. This is a bug and will likely be fixed in the future. +

+ + + diff --git a/man/v0.2.0/nng_ws.html b/man/v0.2.0/nng_ws.html new file mode 100644 index 00000000..70638d1c --- /dev/null +++ b/man/v0.2.0/nng_ws.html @@ -0,0 +1,752 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_ws(7) + + + + + + + +

SYNOPSIS

#include <nng/transport/websocket/ws.h>
+
+int nng_ws_register(void);
+int nng_wss_register(void);

DESCRIPTION

The nng_ws transport provides communication support between +nng sockets across a TCP/IP network using +WebSockets. Both IPv4 and IPv6 +are supported when the underlying platform also supports it.

The protocol details are documented in +WebSocket Mapping for Scalability Protocols.

Registration

Depending upon how the library was built, it may be necessary to +register the transport by calling nng_ws_register. This function +returns zero on success, or an nng error value if the transport +cannot be initialized for any reason.

If TLS support is enabled in the library, secure WebSockets (over TLS v1.2) +can be used as well, but the secure transport may have to be registered using +the nng_wss_register function. (Note that this function will not be +present if TLS support was not enabled in the library.)

URI Format

This transport uses URIs using the scheme ws://, followed by +an IP address or hostname, optionally followed by a colon and an +TCP port number, optionally followed by a path. (If no port number +is specified then port 80 is assumed. If no path is specified then +a path of / is assumed.) +For example, the URI ws://localhost/app/pubsub would use +port 80 on localhost, with the path /app/pubsub.

Secure WebSockets (if enabled) use the scheme wss://, and the default +TCP port number of 443. Otherwise the format is the same as for regular +WebSockets.

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

For example, the same path and port on the IPv6 loopback address (::1) +would be specified as ws://[::1]/app/pubsub.

+ + + + + +

+ +	+When using symbolic names, the name is resolved when the +name is first used. nng won’t become aware of changes in the +name resolution until restart, +usually.^[1] +

+ + + + + +

+ +	+The value specified as the host, if any, will also be used +in the `Host:` HTTP header during HTTP negotiation. +

+
ws://0.0.0.0:9999
+
+
ws://*:9999
+
+
ws://:9999
+

Socket Address

#define NNG_AF_INET    3 (1)
+#define NNG_AF_INET6   4
+#define NNG_MAXADDRLEN 128
+
+typedef struct {
+    // ... (2)
+    uint16_t sa_family;                 // must be NNG_AF_INET
+    uint16_t sa_port;                   // TCP port number
+    uint32_t sa_addr;
+    // ...
+} nng_sockaddr_in;
+
+typedef struct {
+    // ... (2)
+    uint16_t sa_family;                 // must be NNG_AF_INET6
+    uint16_t sa_port;                   // TCP port number
+    uint8_t  sa_addr[16];
+    // ...
+} nng_sockaddr_in6;

+ + + + + + + + + +

1	The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically.
2	Other members may be present, but only those listed here +are suitable for application use.

Transport Options

The following transport options are available. Note that +setting these must be done before the transport is started.

NNG_OPT_WS_REQUEST_HEADERS: +
This value is a string, consisting 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.
+
NNG_OPT_WS_RESPONSE_HEADERS: +
This value is a string, consisting of multiple lines terminated +by CRLF sequences, that can be used to add furthe headers to the +HTTP response sent when connecting. This option can be set on listeners, +and retrieved from pipes.
+
NNG_OPT_WSS_TLS_CONFIG: +
This option is used on an endpoint to access the underlying TLS +configuration object. The value is of type nng_tls_config *. +Note that attempts to set this object may fail on a listener if +the server is already running. Furthermore, attempts to modify the +configuration object will fail if it is already in active use. +This object is only available for wss:// endpoints.
+

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+1. This is a bug and will likely be fixed in the future. +

+ + + diff --git a/man/v0.2.0/nng_zerotier.html b/man/v0.2.0/nng_zerotier.html new file mode 100644 index 00000000..6f3941a9 --- /dev/null +++ b/man/v0.2.0/nng_zerotier.html @@ -0,0 +1,809 @@ +--- +version: 0.2.0 +layout: default +--- + + + + + + + + +nng_zerotier(7) + + + + + + + +

SYNOPSIS

#include <nng/transport/zerotier/zerotier.h>
+
+int nng_zt_register(void);

DESCRIPTION

The nng_zerotier transport provides communication support for +nng applications over a ZeroTier network, +using a Virtual Layer 2 packet facility.

+ + + + + +

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

+ + + + + +

+ +	+The `libzerotiercore` library at present is covered under different +license terms than the rest of nng. Please be careful to review +and adhere to the licensing terms. +

While ZeroTier makes use of the host’s IP stack (and UDP in particular), +this transport does not use or require an IP stack on the virtual +network; thereby mitigating any considerations about IP address management.

This service uses Ethernet type 901 to transport packets. Network rules +must permit this Ethernet type to pass in order to have a functional +network.

+ + + + + +

+ +	+This document assumes that the reader is familiar with ZeroTier +concepts and administration. +

Registration

Depending upon how the library was built, it may be necessary to +register the transport by calling nng_zt_register. This function +returns zero on success, or an nng error value if the transport +cannot be initialized for any reason.

URI Format

This transport uses URIs using the scheme zt://, followed by a network +address (sixteen hexadecimal digits), followed by a / delimiter, +followed by the node number (ten hexadecimal digits) of the listening +node, followed by a service or port number (decimal value, up to 24-bits). +For example, the URI zt://0123456789abdef/fedcba9876:999 indicates +that node fedcba9876 on network 0123456789abcdef listening on port 999.

Listening nodes may use port 0, or *, to indicate that a suitable port +number be selected automatically. Applications using this must get the +selected port address using the nng_listener_getopt function.

Listening nodes may also elide their own node number, as well as the +delimiter separating the node number.

Socket Address

When using an nng_sockaddr structure, the actual structure is of type +struct nng_sockaddr_zt. This type has the following definition:

#define NNG_AF_ZT 5
+
+struct nng_sockaddr_zt {
+    uint16_t sa_family;  // must be NNG_AF_ZT
+    uint64_t sa_nwid;    // 64-bit network ID
+    uint64_t sa_nodeid;  // 40-bit node ID
+    uint32_t sa_port;    // 24-bit application port
+}

The sa_family member will have the value NNG_AF_ZT (5). The remaining +members are, unlike TCP socket address, in native byte order. Only the +lower 24-bits of the sa_port may be used. Likewise only the lower 40-bits +of the sa_nodeid may be used.

Node Presence

By default this transport creates an "ephemeral" node, and used the +same ephemeral node for any additional endpoints created. As this node +is ephemeral, the keys associated with it and all associated data are +located in memory and are discarded upon application termination. If +a persistent node is desired, please see the NNG_OPT_ZT_HOME option +below.

It is possible for a single application to join multiple networks +using the same node, or using separate nodes.

Transport Options

The following transport options are available:

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 +ZeroTier transport is first used. If this value is empty, then an ephemeral +ZeroTier node is created, and no persistent state is used. The default +is to use an ephemeral node.

+ + + + + +

+ +	+If this option is set to different values on different sockets, +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

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

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

This is a read-only integer, representing the ZeroTier network status. +Valid values for this are:

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

nng_zt_network_status_configuring

The ZeroTier node is still configuring, network services are not available.

nng_zt_network_status_ok

The ZeroTier network is up.

nng_zt_network_status_denied

The node does not have permission to join the ZeroTier network.

nng_zt_network_status_notfound

The ZeroTier network is not found.

nng_zt_network_status_error

Some other ZeroTier error has occurred; the network is not available.

nng_zt_network_status_obsolete

The node is running obsolete software; the network is not available.

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

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

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

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

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

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.

COPYRIGHT

This document is supplied under the terms of the +MIT License.

+ + + -- cgit v1.2.3-70-g09d2

libnng(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

Common Functions

Socket Functions

Message Functions

Asynchronous Operations

Protocols

Transports

SEE ALSO

COPYRIGHT

nng(7) Manual Page

NAME

SYNOPSIS

DESCRIPTION

Protocols

Transports

Conceptual Overview

API

SEE ALSO

COPYRIGHT

nng_bus(7) Manual Page

NAME

SYNOPSIS

DESCRIPTION

Socket Operations

Protocol Versions

Protocol Options

Protocol Headers

SEE ALSO

COPYRIGHT

nng_close(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

COPYRIGHT

nng_inproc(7) Manual Page

NAME

SYNOPSIS

DESCRIPTION

Registration

URI Format

Socket Address

Transport Options

SEE ALSO

COPYRIGHT

nng_ipc(7) Manual Page

NAME

SYNOPSIS

DESCRIPTION

Registration

URI Format

Socket Address

Transport Options

SEE ALSO

COPYRIGHT

nng_pair(7) Manual Page

NAME

SYNOPSIS

DESCRIPTION

Socket Operations

Protocol Versions

Polyamorous Mode

Protocol Options

Protocol Headers

SEE ALSO

COPYRIGHT

nng_pub(7) Manual Page

NAME

SYNOPSIS

DESCRIPTION

Socket Operations

Protocol Versions

Protocol Options

Protocol Headers

SEE ALSO