From c4050ecbf846d138a07bfaf238306fb862b9a3d5 Mon Sep 17 00:00:00 2001 From: "Staysail Systems, Inc" Date: Sun, 2 Aug 2020 12:14:46 -0700 Subject: Manual page updates for v1.3.2 --- man/v1.3.2/nng.7.html | 379 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 379 insertions(+) create mode 100644 man/v1.3.2/nng.7.html (limited to 'man/v1.3.2/nng.7.html') diff --git a/man/v1.3.2/nng.7.html b/man/v1.3.2/nng.7.html new file mode 100644 index 00000000..69c59393 --- /dev/null +++ b/man/v1.3.2/nng.7.html @@ -0,0 +1,379 @@ +--- +version: v1.3.2 +layout: manpage_v2 +--- +

nng(7)

+
+

NAME

+
+
+

nng - nanomsg next generation

+
+
+
+
+

SYNOPSIS

+
+
+

cc ['flags'] 'files' -lnng ['libraries']

+
+
+
+
+

DESCRIPTION

+
+
+

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

+
+
+

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

+
+
+

NNG 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 other libraries must ensure that they only +use protocols or transports offered by the other library.

+
+
+

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

+
+
+

NNG 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_pull(7) + +

Pull side of pipeline protocol

+
+nng_push(7) + +

Push side of pipeline 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_ws(7) + +

WebSocket 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 protocol.

+
+
+

Each socket can be used to send and receive messages (if the protocol) +supports it, and implements the appropriate protocol semantics. +For example, sub 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 req 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 accept 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 operating system 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.

+
+
+

Raw Mode

+
+

Most applications will use sockets in normal, or cooked, mode. +This mode provides the full semantics of the protocol. +For example, req sockets will automatically +match a reply to a request, and resend requests periodically if no reply +was received.

+
+
+

There are situations, such as with proxies, +where it is desirable to bypass these semantics and simply pass messages +to and from the socket with no extra semantic handling. +This is possible using raw mode sockets.

+
+
+

Raw mode sockets are generally constructed with a different function, +such as nng_req0_open_raw(). +Using these sockets, the application can simply send and receive messages, +and is responsible for supplying any additional socket semantics. +Typically this means that the application will need to inspect message +headers on incoming messages, and supply them on outgoing messages.

+
+
+ + + + + +
+ + +The nng_device() function only works with raw mode +sockets, but as it only forwards the messages, no additional application +processing is needed. +
+
+
+
+

URLs

+
+

NNG uses universal resource locators (URLs) +following the format specified in +RFC 3986, +including some schemes that are unique +to SP. +The URLs used in NNG are canonicalized as follows, mostly in +accordance with +RFC 3986 6.2.2:

+
+
+
    +
  1. +

    The URL is parsed into scheme, userinfo, host, port, path, query and + fragment components. (Not all of these members are necessarily present.)

    +
    2. +
  2. +

    The scheme, hostname, and port if present, are converted to lower case.

    +
    3. +
  3. +

    Percent-encoded values for + unreserved characters + converted to their unencoded forms.

    +
    4. +
  4. +

    Additionally URL percent-encoded values for characters in the path + and with numeric values larger than 127 (i.e. not ASCII) are decoded.

    +
    5. +
  5. +

    The resulting path is checked for invalid UTF-8 sequences, consisting + of surrogate pairs, illegal byte sequences, or overlong encodings. + If this check fails, then the entire URL is considered invalid.

    +
    6. +
  6. +

    Path segments consisting of . and .. are resolved as per + RFC 3986 6.2.2.3.

    +
    7. +
  7. +

    Further, empty path segments are removed, meaning that duplicate + slash (/) separators are removed from the path.

    +
    8. +
+
+
+

Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing +them is believed to improve both the usability and security of +applications, without violating RFC 3986 itself.

+
+
+ + + + + +
+ + +Port numbers may be service names in some instances, but it is recommended +that numeric port numbers be used when known. +If service names are used, it is recommended that they follow the naming +conventions for C identifiers, and not be longer than 32 characters in length. +This will maximize compatibility across systems and minimize opportunities for +confusion when they are parsed on different systems. +
+
+
+
+
+

API

+
+

The library API is documented at libnng(3).

+
+
+
+
+
+

SEE ALSO

+
+
+

libnng(3), +nng_compat(3compat)

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