--- name: "nng" section: "7" platform: "linux" package: "libnng-dev" version: "1.10.1-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/nng" --- # nng(7) nanomsg next generation ## 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)](/nng_bus/7.md)* *Bus protocol* *[nng\_pair(7)](/nng_pair/7.md)* *Pair protocol* *[nng\_pub(7)](/nng_pub/7.md)* *Publisher side of publish/subscribe protocol* *[nng\_pull(7)](/nng_pull/7.md)* *Pull side of pipeline protocol* *[nng\_push(7)](/nng_push/7.md)* *Push side of pipeline protocol* *[nng\_sub(7)](/nng_sub/7.md)* *Subscriber side of publish/subscribe protocol* *[nng\_rep(7)](/nng_rep/7.md)* *Reply side of request/reply protocol* *[nng\_req(7)](/nng_req/7.md)* *Request side of request/reply protocol* *[nng\_respondent(7)](/nng_respondent/7.md)* *Respondent side of survey protocol* *[nng\_surveyor(7)](/nng_surveyor/7.md)* *Surveyor side of survey protocol* ### Transports *[nng\_inproc(7)](/nng_inproc/7.md)* *Intra-process transport* *[nng\_ipc(7)](/nng_ipc/7.md)* *Inter-process transport* *[nng\_socket(7)](/nng_socket/7.md)* *BSD socket transport* *[nng\_tls(7)](/nng_tls/7.md)* *TLSv1.2 over TCP transport* *[nng\_tcp(7)](/nng_tcp/7.md)* *TCP (and TCPv6) transport* *[nng\_ws(7)](/nng_ws/7.md)* *WebSocket transport* *[nng\_zerotier(7)](/nng_zerotier/7.md)* *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.* **Tip**\ *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.* *The scheme, hostname, and port if present, are converted to lower case.* *3.* *Percent-encoded values for**unreserved characters \* *converted to their unencoded forms.* *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.* *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.* *Path segments consisting of* `.` *and* `..` *are resolved as per* *RFC 3986 6.2.2.3 \.* *7.* *Further, empty path segments are removed, meaning that duplicate* *slash (*`/`*) separators are removed from the path.* *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.* **Tip**\ *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)](/libnng/3.md).* ## SEE ALSO *[libnng(3)](/libnng/3.md),* *nng\_compat(3compat)*