LIBNNG(3)

📦
version 1.12.0 · 4 versions
, in ubuntu stonking

💖 LIBNNG(3) — nanomsg next generation library 💖

libnng — the manual page, bestie edition. Yes it's nng, the nanomsg next generation library, and yes she is that girl. 🎀

✨ NAME ✨

libnng — nanomsg next generation library 🦋

✨ SYNOPSIS ✨

cc [flags] files -lnng [libraries]

like. that's it. that's the whole build line. you compile your stuff, you link -lnng, you go live your life. 💅

✨ DESCRIPTION ✨

okay so picture this: distributed applications have a LOT of communication problems and they're all kind of the same problems over and over again. NNG is a common messaging framework built specifically to solve those common communication problems. no cap. 🫶

and the way you talk to it is through a C language API. that's the whole vibe.

🌸 Common Functions

these are the little everyday helpers that live in libnng. the utility squad. the ones you call constantly and never think about:

  • nng_alloc — allocate memory 🧚
  • nng_free — free memory (yes, the sequel)
  • nng_strdup — duplicate string
  • nng_strerror — return an error description
  • nng_strfree — free string
  • nng_version — report library version 👑

ngl nng_strerror is lowkey doing the most for you every single time something explodes. thank her.

🌈 Socket Functions

and these ones? these operate on sockets. this is where the main character energy lives:

  • nng_close — close socket
  • nng_dial — create and start dialer
  • nng_getopt — get socket option
  • nng_listen — create and start listener
  • nng_recv — receive data
  • nng_send — send data (the iconique counterpart)
  • nng_setopt — set socket option (DEPRECATED)
  • nng_socket_get — get socket option
  • nng_socket_id — get numeric socket identifier
  • nng_socket_raw — is the socket raw
  • nng_socket_proto_id — get the socket protocol identifier
  • nng_socket_proto_name — get the socket protocol name
  • nng_socket_set — set socket option
  • nng_sub_subscribe — manage subscriptions
🚨 bestie listen. nng_setopt is marked DEPRECATED. she still exists, she still works, but she is NOT the moment anymore. do not build your new thing on her. periodt. 💀

and that's part 1, we are literally just getting started — more pages are coming so don't go anywhere bestie 💜

💖 Connection Management 💖

okay so these functions are used with either listeners, or dialers. Listeners accept incoming connection requests, and dialers make them. That's the whole dynamic, bestie — listeners are the ones saying "come thru," dialers are the ones making the first move. 💌

  • nng_dial — create and start dialer
  • nng_dialer_close — close dialer
  • nng_dialer_create — create dialer
  • nng_dialer_get — get dialer option
  • nng_dialer_getopt — get dialer option (DEPRECATED)
  • nng_dialer_id — get numeric dialer identifier
  • nng_dialer_set — set dialer option
  • nng_dialer_setopt — set dialer option (DEPRECATED)
  • nng_dialer_start — start dialer
  • nng_listen — create and start listener
  • nng_listener_close — close listener
  • nng_listener_create — create listener
  • nng_listener_get — get listener option
  • nng_listener_getopt — get listener option (DEPRECATED)
  • nng_listener_id — get numeric listener identifier
  • nng_listener_set — set listener option
  • nng_listener_setopt — set listener option (DEPRECATED)
  • nng_listener_start — start listener
  • nng_pipe_close — close pipe
  • nng_pipe_dialer — return dialer that created pipe
  • nng_pipe_get — get pipe option
  • nng_pipe_getopt — get pipe option (DEPRECATED)
  • nng_pipe_id — get numeric pipe identifier
  • nng_pipe_listener — return listener that created pipe
  • nng_pipe_notify — register pipe notification callback
  • nng_pipe_socket — return owning socket for pipe

🦋 Message Handling Functions 🦋

If your app wants the richest part of libnng, you're gonna want the message API — a message structure gets passed between functions. This API provides the most powerful support for zero-copy. 💅✨

Okay so here's the whole roster of message functions — the header is one thing, the body is another, and almost everyone only ever touches the body. The body carries your user payload; the header carries protocol-specific header info. Cute, right?

  • nng_msg_alloc — allocate a message
  • nng_msg_append — append to message body
  • nng_msg_body — return message body
  • nng_msg_capacity — return capacity allocated for message body
  • nng_msg_chop — remove data from end of message body
  • nng_msg_clear — clear message body
  • nng_msg_dup — duplicate a message
  • nng_msg_free — free a message
  • nng_msg_get_pipe — get pipe for message
  • nng_msg_insert — prepend to message body
  • nng_msg_len — return the message body length
  • nng_msg_realloc — reallocate a message
  • nng_msg_reserve — reserve storage for message body
  • nng_msg_set_pipe — set pipe for message
  • nng_msg_trim — remove data from start of message body
  • nng_recvmsg — receive a message
  • nng_sendmsg — send a message

🦋 Message Header Handling 🦋

Tip — bestie, most apps will never need these. Message headers only carry protocol-specific content, periodt. But if you're living that raw mode life, you may need to poke at the header of messages. iykyk.
  • nng_msg_header — return message header
  • nng_msg_header_append — append to message header
  • nng_msg_header_chop — remove data from end of message header
  • nng_msg_header_clear — clear message header
  • nng_msg_header_insert — prepend to message header
  • nng_msg_header_len — return the message header length
  • nng_msg_header_trim — remove data from start of message header

✨ Asynchronous Operations ✨

So most apps interact with NNG synchronously, meaning functions like nng_send will lowkey hold the calling thread hostage until the operation has completed. Like, block and wait, bestie. 💅

Note — not me telling you that synchronous operations which send messages may return before the message has actually been received, or even transmitted. Fr fr: these functions return as soon as the message was successfully queued for delivery. That's it. That's the whole story. 🙈

Asynchronous operations? Completely different vibe. The calling thread kicks the operation off, but control returns to the calling thread immediately. Then, when the operation is subsequently completed — successful or not, no judgment, both are valid — a user-supplied function gets executed. Callback era. 🎀

A context structure, an nng_aio, is allocated and associated with each asynchronous operation. And here's the rule: only a single asynchronous operation may be associated with an nng_aio at any time. One. Singular. Don't be messy about it. 👑

✨ the asynchronous model girlies ✨

okay so these are all the functions you'll be living in when you're doing stuff asynchronously — like, nothing waits around blocking your thread, everything's giving "i'll text you back later" energy 💅

  • nng_aio_abort — abort asynchronous I/O operation
  • nng_aio_alloc — allocate asynchronous I/O handle
  • nng_aio_begin — begin asynchronous I/O operation
  • nng_aio_busy — test if asynchronous I/O is busy
  • nng_aio_cancel — cancel asynchronous I/O operation
  • nng_aio_count — return number of bytes transferred
  • nng_aio_defer — defer asynchronous I/O operation
  • nng_aio_finish — finish asynchronous I/O operation
  • nng_aio_free — free asynchronous I/O handle
  • nng_aio_get_input — return input parameter
  • nng_aio_get_msg — get message from an asynchronous receive
  • nng_aio_get_output — return output result
  • nng_aio_reap — reap asynchronous I/O handle
  • nng_aio_result — return result of asynchronous operation
  • nng_aio_set_input — set input parameter
  • nng_aio_set_iov — set scatter/gather vector
  • nng_aio_set_msg — set message for an asynchronous send
  • nng_aio_set_output — set output result
  • nng_aio_set_timeout — set asynchronous I/O timeout
  • nng_aio_stop — stop asynchronous I/O operation
  • nng_aio_wait — wait for asynchronous I/O operation
  • nng_recv_aio — receive message asynchronously
  • nng_send_aio — send message asynchronously
  • nng_sleep_aio — sleep asynchronously

🎀 Protocols 🎀

and these bad boys? they're how you build yourself a socket that's committed to one specific protocol. pick your fighter, bestie ✨

  • nng_bus_open — open a bus socket
  • nng_pair_open — open a pair socket
  • nng_pub_open — open a pub socket
  • nng_pull_open — open a pull socket
  • nng_push_open — open a push socket
  • nng_rep_open — open a rep socket
  • nng_req_open — open a req socket
  • nng_respondent_open — open a respondent socket
  • nng_sub_open — open a sub socket
  • nng_surveyor_open — open a surveyor socket

🦋 that's the whole roster, no cap 🦋

💫 Transports 💫

okay so these functions register a transport for use, right? but bestie. plot twist — this is no longer necessary, and applications should not call these functions anymore. that's not me being dramatic, that's the manpage. periodt. 🙅‍♀️

so like, they're still documented (we don't gatekeep the lore) but every single one of them is DEPRECATED. read them for the history lesson, not for your new project. 💅

  • nng_inproc_register — register inproc transport (DEPRECATED)
  • nng_ipc_register — register IPC transport (DEPRECATED)
  • nng_tcp_register — register TCP transport (DEPRECATED)
  • nng_tls_register — register TLS transport (DEPRECATED)
  • nng_ws_register — register WebSocket transport (DEPRECATED)
  • nng_wss_register — register WebSocket Secure transport (DEPRECATED)
  • nng_zt_register — register ZeroTier transport (DEPRECATED)
fr fr whisper: if you're out here calling these in 2024+ code, we need to talk. they're deprecated. the library handles this now.

🧠💅 Protocol Contexts 💅🧠

now THIS is the good stuff. these functions let you pull the protocol processing out of a socket object and into a whole separate context. why do we care? because it means you can spin up multiple contexts on a single socket for concurrent applications. one socket, many main characters. that's range. 👑

  • nng_ctx_close — close context
  • nng_ctx_get — get context option
  • nng_ctx_getopt — get context option (DEPRECATED)
  • nng_ctx_id — get numeric context identifier
  • nng_ctx_open — create context
  • nng_ctx_recv — receive message using context asynchronously
  • nng_ctx_recvmsg — receive a message using context
  • nng_ctx_send — send message using context asynchronously
  • nng_ctx_sendmsg — send a message using context
  • nng_ctx_set — set context option
  • nng_ctx_setopt — set context option (DEPRECATED)
heads up bestie: see how nng_ctx_getopt and nng_ctx_setopt are tagged DEPRECATED? yeah. they're the old way. nng_ctx_get and nng_ctx_set are the ones you actually want. the vibe check said "evolve." 🦋

🔀 Devices, Relays 🔀

last lil family in this part, and honestly? iconic behaviour. this one is a whole function family (okay it's one function, but the concept is a family) for building forwarders or relayers — the lil guys that take messages from one socket and route them on over to another socket. message traffic controller energy. 🚦✨

  • nng_device — message forwarding device

so that's your relayer. route it, forward it, slay it. 🫶

💖 Statistics 💖

okay bestie, so these functions are the whole stats vibe — they give you access to statistics that can be used to observe program behaviors and as an aid in troubleshooting. It’s giving “I know what my code is doing” energy, fr fr. 🔍✨

  • nng_stat_bool — get statistic Boolean value
  • nng_stat_child — get child statistic
  • nng_stat_name — get statistic description
  • nng_stat_find — find statistic by name
  • nng_stat_find_dialer — find dialer statistics
  • nng_stat_find_listener — find listener statistics
  • nng_stat_find_socket — find socket statistics
  • nng_stat_name — get statistic name
  • nng_stat_next — get next statistic
  • nng_stat_string — get statistic string value
  • nng_stat_timestamp — get statistic timestamp
  • nng_stat_type — get statistic type
  • nng_stat_unit — get statistic unit
  • nng_stat_value — get statistic numeric value
  • nng_stats_free — free statistics
  • nng_stats_get — get statistics

🌐 URL Object 🌐

Common functionality is supplied for parsing and handling universal resource locators (URLS). Yes, URLS with the S, we are not taking questions at this time 💅

  • nng_url_clone — clone URL structure
  • nng_url_free — free URL structure
  • nng_url_parse — create URL structure from string

📝 Logging Support 📝

Common functionality for message logging. Because sometimes you need receipts, bestie. 🧾💖

  • nng_log — log a message
  • nng_log_set_facility — set log facility
  • nng_log_set_level — set log level
  • nng_log_set_logger — set logging handler

✨ Supplemental API ✨

Okay bestie, so these supplemental functions? They're not like intrinsic to building network applications with NNG — they're not the main character of the networking story 💅. But they're here anyway, as a convenience, to help you out when you're trying to make portable applications. Think of them as the little besties that carry your bags while you do the big networking stuff 🫶

Here's the full squad, no gatekeeping:

  • nng_clock — get time ⏰
  • nng_cv_alloc — allocate condition variable
  • nng_cv_free — free condition variable
  • nng_cv_until — wait for condition or timeout ⏳
  • nng_cv_wait — wait for condition
  • nng_cv_wake — wake all waiters
  • nng_cv_wake1 — wake one waiter
  • nng_id_map — identifier based mapping table 🗺️
  • nng_msleep — sleep for milliseconds 😴
  • nng_mtx_alloc — allocate mutex
  • nng_mtx_free — free mutex
  • nng_mtx_lock — lock mutex 🔒
  • nng_mtx_unlock — unlock mutex 🔓
  • nng_opts_parse — parse command line options
  • nng_random — get random number 🎲
  • nng_socket_pair — create connected pair of BSD sockets
  • nng_thread_create — create thread 🧵
  • nng_thread_destroy — reap thread
  • nng_thread_set_name — set thread name 🏷️

🌊 Byte Streams 🌊

And these functions? They're the ones you can use with byte streams 💧. Fr fr, they're considered low-level — like, you reach for them when the higher level functions that use Scalability Protocols are just not it for whatever you're doing 🙈. Not inappropriate in a bad way, just inappropriate for the vibe.

So like — byte streams, bestie, are what you get when you want a raw connection: an actual TCP connection, a named pipe, that kind of thing 🫶 Each one is wrapped up in an nng_stream object, and you never just ✨materialize✨ one out of thin air. They come from either nng_stream_dialer or nng_stream_listener objects. The dialer slides out and makes the connection happen; the listener sits there all cute until somebody shows up. 🎀

Here's the whole squad of byte stream functions, every single one, no skips:

  • nng_stream_close — close byte stream 💅
  • nng_stream_dialer_alloc — allocate byte stream dialer ✨
  • nng_stream_dialer_close — close byte stream dialer
  • nng_stream_dialer_dial — initiate outgoing byte stream 🔥
  • nng_stream_dialer_free — free byte stream dialer
  • nng_stream_dialer_get — get option from byte stream dialer
  • nng_stream_dialer_set — set option on byte stream dialer
  • nng_stream_free — free byte stream
  • nng_stream_get — get option from byte stream
  • nng_stream_listener_accept — accept incoming byte stream 🫶
  • nng_stream_listener_alloc — allocate byte stream listener
  • nng_stream_listener_close — close byte stream listener
  • nng_stream_listener_free — free byte stream listener
  • nng_stream_listener_get — get option from byte stream listener
  • nng_stream_listener_listen — bind byte stream listener to address 🌈
  • nng_stream_listener_set — set option on byte stream listener
  • nng_stream_recv — receive from byte stream 💜
  • nng_stream_send — send to byte stream 💌
  • nng_stream_set — set option on byte stream

🦋 HTTP Support 🦋

Okay so this one depends on how your library was built, and that's the tea: the library may be configured with support for HTTP 💅 — and the rule is that this will be the case if WebSocket support is configured as well. So no WebSocket, no HTTP party. Periodt.

When you do have it, though? You get access to functionality to support the creation of HTTP servers and clients, and, if TLS support is present, HTTP/S ones too. both flavors, iconically 👑

✨ Common HTTP Functions ✨

Okay bestie, these are the little guys you'll be texting all day long — the functions that handle HTTP requests, responses, and connections. Every single one, in order, no skips, let's go 🫶

  • nng_http_conn_close — closes down that HTTP connection, bye bye 👋
  • nng_http_conn_read — reads from an HTTP connection 📖
  • nng_http_conn_read_all — reads everything from an HTTP connection, no crumbs left 🍪
  • nng_http_conn_read_req — reads an HTTP request 📨
  • nng_http_conn_read_res — reads an HTTP response 📬
  • nng_http_conn_write — writes to an HTTP connection ✍️
  • nng_http_conn_write_all — writes all of it to an HTTP connection, commitment issues = none 💅
  • nng_http_conn_write_req — writes an HTTP request 📤
  • nng_http_conn_write_res — writes an HTTP response 📥
  • nng_http_req_add_header — adds an HTTP request header ➕
  • nng_http_req_alloc — allocates an HTTP request structure 🏗️
  • nng_http_req_copy_data — copies the HTTP request body 📋
  • nng_http_req_del_header — deletes an HTTP request header 🗑️
  • nng_http_req_free — frees that HTTP request structure, so it stops living rent free 🏠
  • nng_http_req_get_data — gets the HTTP request body 🔍
  • nng_http_req_get_header — returns an HTTP request header 🔙
  • nng_http_req_get_method — returns the HTTP request method (the verb energy fr) 🏷️
  • nng_http_req_get_uri — returns the HTTP request URI 🌐
  • nng_http_req_get_version — returns the HTTP request protocol version 🔢
  • nng_http_req_reset — resets the HTTP request structure, starting fresh, main character rebirth arc 🦋
  • nng_http_req_set_data — sets the HTTP request body 🩹
  • nng_http_req_set_header — sets an HTTP request header 🎀
  • nng_http_req_set_method — sets the HTTP request method ⚙️
  • nng_http_req_set_uri — sets the HTTP request URI 🧭
  • nng_http_req_set_version — sets the HTTP request protocol version 🔧
  • nng_http_res_add_header — adds an HTTP response header ➕
  • nng_http_res_alloc — allocates an HTTP response structure 🏗️
  • nng_http_res_alloc_error — allocates an HTTP error response, for when things are giving chaos 😭
  • nng_http_res_copy_data — copies the HTTP response body 📋
  • nng_http_res_del_header — deletes an HTTP response header 🗑️
  • nng_http_res_free — frees the HTTP response structure 🏠
  • nng_http_res_get_data — gets the HTTP response body 🔍
  • nng_http_res_get_header — returns an HTTP response header 🔙
  • nng_http_res_get_reason — returns the HTTP response reason 💬

…and the rest of the response girlies, finishing up the roster 💅

  • nng_http_res_get_status — hands you back the HTTP response status ✨
  • nng_http_res_get_version — hands you back the HTTP response protocol version 🌸
  • nng_http_res_reset — wipes the HTTP response structure back to a clean slate 🧼
  • nng_http_res_set_data — sets the HTTP response body 🍓
  • nng_http_res_set_header — sets an HTTP response header 📨
  • nng_http_res_set_reason — sets the HTTP response reason 💬
  • nng_http_res_set_status — sets the HTTP response status 🔢
  • nng_http_res_set_version — sets the HTTP response protocol version 🏷️

👑 HTTP Client Functions 👑

These functions are intended for use with HTTP client applications. Like, if you're the one making the requests, this is your section bestie 🫶

  • nng_http_client_alloc — allocates an HTTP client 🌱
  • nng_http_client_connect — establishes the HTTP client connection 🔌
  • nng_http_client_free — frees the HTTP client 💀 (the good kind of free, don't panic)
  • nng_http_client_get_tls — gets the HTTP client TLS configuration 🔐
  • nng_http_client_set_tls — sets the HTTP client TLS configuration 🔒
  • nng_http_client_transact — performs one HTTP transaction ✨
  • nng_http_conn_transact — performs one HTTP transaction on a connection 🌈

HTTP Server Functions 🌐✨

These ones are for when you're building an HTTP server app, like actually serving requests to people. Bestie, this is where the main character energy lives fr fr 💅

  • nng_http_handler_alloc — allocate HTTP server handler
  • nng_http_handler_collect_body — set HTTP handler to collect request body
  • nng_http_handler_free — free HTTP server handler
  • nng_http_handler_get_data — return extra data for HTTP handler
  • nng_http_handler_set_data — set extra data for HTTP handler
  • nng_http_handler_set_host — set host for HTTP handler
  • nng_http_handler_set_method — set HTTP handler method
  • nng_http_handler_set_tree — set HTTP handler to match trees
  • nng_http_hijack — hijack HTTP server connection
  • nng_http_server_add_handler — add HTTP server handler
  • nng_http_server_del_handler — delete HTTP server handler
  • nng_http_server_get_addr — get HTTP server address
  • nng_http_server_get_tls — get HTTP server TLS configuration
  • nng_http_server_hold — get and hold HTTP server instance
  • nng_http_server_release — release HTTP server instance
  • nng_http_server_set_error_file — set custom HTTP error file
  • nng_http_server_set_error_page — set custom HTTP error page
  • nng_http_server_set_tls — set HTTP server TLS configuration
  • nng_http_server_res_error — use HTTP server error page
  • nng_http_server_start — start HTTP server
  • nng_http_server_stop — stop HTTP server

TLS Configuration Objects 🔐🦋

The following functions are used to manipulate transport layer security (TLS) configuration objects. The way that most of these functions are so niche that even actual TLS applications won't touch them… yeah, that's the vibe 😭 Most of y'all will never call these, and that's totally okay bestie, no cap.

Note

These functions will only be present if the library has been built with TLS support. like, if your build didn't have TLS turned on, these just… don't exist bestie 💀 don't come for me, that's just how it is.

  • nng_tls_config_alloc — allocate a TLS configuration ✨
  • nng_tls_config_auth_mode — set the authentication mode 🔐
  • nng_tls_config_ca_chain — set the certificate authority chain 🎀
  • nng_tls_config_ca_file — load the certificate authority from a file 📂
  • nng_tls_config_cert_key_file — load your own certificate and key from a file 🗝️
  • nng_tls_config_psk — set the pre-shared key and identity 🤝
  • nng_tls_config_own_cert — set your own certificate and key 👑
  • nng_tls_config_free — free the TLS configuration 🧹
  • nng_tls_config_server_name — set the remote server name 🛰️

🌈 SEE ALSO 🌈

okay so if you wanna keep vibing through the docs, these are the ones to tap next:

and that's the whole page, babe 🫶

this was LIBNNG(3), dated 2026-06-30 💅 tagged and dated, archived, iconic, periodt. go forth and configure your TLS like the main character you are ✨🦋💖

📦 where this page comes from