NNG(7)

📦
version 1.12.0 · 4 versions
, in ubuntu stonking

💖 NNG 💖

okay bestie, welcome to nng — nanomsg next generation — and honestly? it's giving foundational. it's the manual page. the mother page. every other page in this reference manual is basically its child. let's get into it 🫶

✨ SYNOPSIS ✨

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

that's it. that's the whole ritual. link against -lnng and you're in the group chat 💅

🌸 DESCRIPTION 🌸

NNG gives you a common messaging framework made to solve the regular, everyday communication problems that pop up in distributed applications. it ships with a bunch of protocols and a bunch of transports, and they are not the same thing, bestie, do not confuse them 😭

The protocols implement the semantics that go with particular communications scenarios — think RPC style services, service discovery, publish/subscribe, and so on and so forth. ✨

The transports are the support system underneath — TCP, IPC, websockets, you name it, and so forth. 🦋

NNG is designed so that making new transports is easy, and making new protocols is also possible, just, y'know, to a lesser extent. we're honest about that here. 💀

NNG is wire compatible with the SP protocols described in the nanomsg project. that means projects using libnanomsg (<https://github.com/nanomsg/nanomsg>) can inter-operate with nng, and also with any other conforming implementation. (One such implementation is mangos — <https://github.com/go-mangos/mangos>.) 💖

heads up: applications using NNG that want to talk to other libraries must make sure they only use protocols or transports that the other library actually offers. no cap. otherwise the vibe check fails.

NNG also offers a compatible API, which means legacy code can be recompiled or relinked against NNG. but — and this is the part nobody likes — when you do that, support for certain enhancements or features will likely be absent, and the application developer is gonna have to use the new-style API. it's fine. it's growth. 🌱

NNG is implemented in pure C, periodt. if you need bindings for other languages, please check the website (<http://nanomsg.org/>). 👑

🎀 Protocols 🎀

🦋 Transports 🦋

💜 Conceptual Overview 💜

NNG presents a socket view of networking. The sockets are constructed using protocol-specific functions, because a given socket implements precisely one protocol. one socket, one protocol, no polyamory here 🫶

Each socket can be used to send and receive messages (if the protocol supports it, obviously — read the room), and it implements the appropriate protocol semantics. For example, sub sockets automatically filter incoming messages to discard those for topics that have not been subscribed. iconic behaviour, honestly. ✨

NNG sockets are message oriented, so 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. main character protocols 💅)

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 — it's a free country 🌈) 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. so loyal. so patient. 😭

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. fr fr, don't overthink it.

🌈 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. so thoughtful of them 🥹

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. you're on your own now, bestie. you got this. 💪

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 (<https://tools.ietf.org/html/rfc3986>), 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 (<https://tools.ietf.org/html/rfc3986#section-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 (<https://tools.ietf.org/html/rfc3986#section-2.3>) 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 (<https://tools.ietf.org/html/rfc3986#section-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. we're just being extra. responsibly. 💅

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). go read it. it's good for you. 📚

🔍 SEE ALSO 🔍

okay that's the whole page, bestie, you ate 💅✨ this was NNG(7) from the NNG Reference Manual, dated 2026-06-30. mwah, go build something cute 🎀🦋💖

📦 where this page comes from