This documentation is for the TIP (development tree) of NNG and may represent unreleased changes or functionality that is experimental, and is subject to change before release. The latest released version is v1.8.0. See the documentation for v1.8.0 for the most up-to-date information.

NNG Reference Manual

Section 1: Commands and Utilities

This section documents utilities and programs that are included with the distribution.

nngcat(1)

command line access to Scalability Protocols

Section 3: Library Functions

This section documents core libary functions supporting Scalability Protocols.

Most Scalability Protocols applications can be written using just the functions documented in this section, as this represents the primary API for building such applications.

libnng(3)

nanomsg next generation library

nng_aio_abort(3)

abort asynchronous I/O operation

nng_aio_alloc(3)

allocate asynchronous I/O handle

nng_aio_begin(3)

begin asynchronous I/O operation

nng_aio_busy(3)

test if asynchronous I/O is busy

nng_aio_cancel(3)

cancel asynchronous I/O operation

nng_aio_count(3)

return number of bytes transferred

nng_aio_defer(3)

defer asynchronous I/O operation

nng_aio_finish(3)

finish asynchronous I/O operation

nng_aio_free(3)

free asynchronous I/O handle

nng_aio_get_input(3)

return input parameter

nng_aio_get_msg(3)

get message from asynchronous receive

nng_aio_get_output(3)

return output result

nng_aio_result(3)

return result of asynchronous operation

nng_aio_set_input(3)

set input parameter

nng_aio_set_iov(3)

set scatter/gather vector

nng_aio_set_msg(3)

set message for asynchronous send

nng_aio_set_output(3)

set output result

nng_aio_set_timeout(3)

set asynchronous I/O timeout

nng_aio_stop(3)

stop asynchronous I/O operation

nng_aio_wait(3)

wait for asynchronous I/O operation

nng_alloc(3)

allocate memory

nng_bus_open(3)

create bus socket

nng_close(3)

close socket

nng_ctx_close(3)

close context

nng_ctx_get(3)

get context option

nng_ctx_getopt(3)

get context option

nng_ctx_id(3)

return numeric context identifier

nng_ctx_open(3)

create context

nng_ctx_recv(3)

receive message using context asynchronously

nng_ctx_recvmsg(3)

receive message using socket

nng_ctx_send(3)

send message using context asynchronously

nng_ctx_sendmsg(3)

send message using context

nng_ctx_set(3)

set context option

nng_ctx_setopt(3)

set context option

nng_device(3)

message forwarding device

nng_dial(3)

create and start dialer

nng_dialer_close(3)

close dialer

nng_dialer_create(3)

create dialer

nng_dialer_get(3)

get dialer option

nng_dialer_getopt(3)

get dialer option

nng_dialer_id(3)

return numeric dialer identifier

nng_dialer_set(3)

set dialer option

nng_dialer_setopt(3)

set dialer option

nng_dialer_start(3)

start dialer

nng_free(3)

free memory

nng_getopt(3)

get socket option

nng_inproc_register(3)

register inproc transport

nng_ipc_register(3)

register ipc transport

nng_listen(3)

create and start listener

nng_listener_close(3)

close listener

nng_listener_create(3)

create listener

nng_listener_get(3)

get listener option

nng_listener_getopt(3)

get listener option

nng_listener_id(3)

return numeric listener identifier

nng_listener_set(3)

set listener option

nng_listener_setopt(3)

set listener option

nng_listener_start(3)

start listener

nng_log(3)

log messages

nng_log_get_level(3)

get minimum level for logging messagse

nng_log_set_facility(3)

set facility used for log messages

nng_log_set_level(3)

set minimum level for logging messagse

nng_log_set_logger(3)

set logging handler

nng_msg_alloc(3)

allocate a message

nng_msg_append(3)

append to message body

nng_msg_body(3)

return message body

nng_msg_capacity(3)

return message body length

nng_msg_chop(3)

remove data from end of message body

nng_msg_clear(3)

clear message body content

nng_msg_dup(3)

duplicate a message

nng_msg_free(3)

free a message

nng_msg_get_pipe(3)

get pipe for message

nng_msg_header(3)

return message header

nng_msg_header_append(3)

append to message header

nng_msg_header_chop(3)

remove data from end of message header

nng_msg_header_clear(3)

clear message header

nng_msg_header_insert(3)

prepend to message header

nng_msg_header_len(3)

return message header length

nng_msg_header_trim(3)

remove data from start of message header

nng_msg_insert(3)

prepend to message body

nng_msg_len(3)

return message body length

nng_msg_realloc(3)

reallocate a message

nng_msg_reserve(3)

reserve storage for a message

nng_msg_set_pipe(3)

set pipe for message

nng_msg_trim(3)

remove data from start of message body

nng_pair_open(3)

create pair socket

nng_pipe_close(3)

close pipe

nng_pipe_dialer(3)

return dialer that created pipe

nng_pipe_get(3)

get pipe option

nng_pipe_getopt(3)

get pipe option

nng_pipe_id(3)

return numeric pipe identifier

nng_pipe_listener(3)

return listener that created pipe

nng_pipe_notify(3)

register pipe notification callback

nng_pipe_socket(3)

return owning socket for pipe

nng_pub_open(3)

create pub socket

nng_pull_open(3)

create pull socket

nng_push_open(3)

create push socket

nng_recv(3)

recv data

nng_recv_aio(3)

receive message asynchronously

nng_recvmsg(3)

receive a message

nng_rep_open(3)

create rep socket

nng_req_open(3)

create req socket

nng_respondent_open(3)

create respondent socket

nng_send(3)

send data

nng_send_aio(3)

send message asynchronously

nng_sendmsg(3)

send message

nng_setopt(3)

set socket option

nng_sleep_aio(3)

sleep asynchronously

nng_socket_get(3)

get socket option

nng_socket_id(3)

return numeric socket identifier

nng_socket_set(3)

set socket option

nng_stat_bool(3)

get statistic Boolean value

nng_stat_child(3)

get child statistic

nng_stat_desc(3)

get statistic description

nng_stat_find(3)

find statistic by name

nng_stat_find_dialer(3)

find dialer statistics

nng_stat_find_listener(3)

find listener statistics

nng_stat_find_socket(3)

find socket statistics

nng_stat_name(3)

get statistic name

nng_stat_next(3)

get next statistic

nng_stat_string(3)

get statistic string value

nng_stat_timestamp(3)

get statistic timestamp

nng_stat_type(3)

get statistic type

nng_stat_unit(3)

get statistic unit

nng_stat_value(3)

get statistic numeric value

nng_stats_free(3)

free statistics snapshot

nng_stats_get(3)

get statistics snapshot

nng_str_sockaddr(3)

get string representation of socket address

nng_strdup(3)

duplicate string

nng_strerror(3)

return an error description

nng_strfree(3)

free memory

nng_sub_open(3)

create sub socket

nng_surveyor_open(3)

create surveyor socket

nng_tcp_register(3)

register tcp transport

nng_tls_register(3)

register tls transport

nng_url_clone(3)

clone URL structure

nng_url_free(3)

free a URL structure

nng_url_parse(3)

create URL structure from a string

nng_version(3)

report library version

nng_ws_register(3)

register WebSocket transport

nng_wss_register(3)

register WebSocket secure transport

nng_zt_register(3)

register ZeroTier transport

Section 3compat: Compatible Library Functions

This section documents the nanomsg 1.0 libary compatible functions.

These functions are provided as a transition aid, for application developers coming to NNG from libnanomsg, and are discouraged from use in new applications.

While this is discouraged for long term use, as a transition aid applications may use the value returned by the nng_socket_id() in these functions just like a socket descriptor (as if the socket were opened via nn_socket()). This sort of API intermixing should only be used during transition from the legacy API to the new API.

nn_allocmsg(3compat)

allocate message (compatible API)

nn_bind(3compat)

accept connections from remote peers (compatible API)

nn_close(3compat)

close socket (compatible API)

nn_cmsg(3compat)

message control data (compatible API)

nn_connect(3compat)

connect to remote peer (compatible API)

nn_device(3compat)

create forwarding device (compatible API)

nn_errno(3compat)

return most recent error (compatible API)

nn_freemsg(3compat)

free message (compatible API)

nn_get_statistic(3compat)

get statistic (stub)

nn_getsockopt(3compat)

get socket option (compatible API)

nn_poll(3compat)

poll sockets (compatible API)

nn_reallocmsg(3compat)

reallocate message (compatible API)

nn_recv(3compat)

receive data (compatible API)

nn_recvmsg(3compat)

receive message (compatible API)

nn_send(3compat)

send data (compatible API)

nn_sendmsg(3compat)

send message (compatible API)

nn_setsockopt(3compat)

set socket option (compatible API)

nn_shutdown(3compat)

shut down endpoint (compatible API)

nn_socket(3compat)

create socket (compatible API)

nn_strerror(3compat)

return message for error (compatible API)

nn_term(3compat)

terminate library (compatible API)

nng_compat(3compat)

compatibility with nanomsg 1.0

Section 3http: Supplemental HTTP Functions

This section documents supplemental HTTP (HyperText Transport Protocol) support functions that are available.

These functions can be used in conjunction with the WebSocket transport for Scalability Protocols, or they may be used to construct other types of applications that communicate using HTTP.

It is also possible to combine the two, such that an HTTP server providing static or dynamic content can also be used to host one or more Scalability Protocols sockets.

At present NNG only supports HTTP/1.0 and HTTP/1.1.

nng_http_client_alloc(3http)

allocate HTTP client

nng_http_client_connect(3http)

establish HTTP client connection

nng_http_client_free(3http)

free HTTP client

nng_http_client_get_tls(3http)

get HTTP client TLS configuration

nng_http_client_set_tls(3http)

set HTTP client TLS configuration

nng_http_client_transact(3http)

perform one HTTP transaction

nng_http_conn_close(3http)

close HTTP connection

nng_http_conn_read(3http)

read from HTTP connection

nng_http_conn_read_all(3http)

read all from HTTP connection

nng_http_conn_read_req(3http)

read HTTP request

nng_http_conn_read_res(3http)

read HTTP response

nng_http_conn_transact(3http)

perform one HTTP transaction on connection

nng_http_conn_write(3http)

write to HTTP connection

nng_http_conn_write_all(3http)

write all to HTTP connection

nng_http_conn_write_req(3http)

write HTTP request

nng_http_conn_write_res(3http)

write HTTP response

nng_http_handler_alloc(3http)

allocate HTTP server handler

nng_http_handler_collect_body(3http)

set HTTP handler to collect request body

nng_http_handler_free(3http)

free HTTP server handler

nng_http_handler_get_data(3http)

return extra data for HTTP handler

nng_http_handler_set_data(3http)

set extra data for HTTP handler

nng_http_handler_set_host(3http)

set host for HTTP handler

nng_http_handler_set_method(3http)

set HTTP handler method

nng_http_handler_set_tree(3http)

set HTTP handler to match trees

nng_http_hijack(3http)

hijack HTTP server connection

nng_http_req_add_header(3http)

add HTTP request header

nng_http_req_alloc(3http)

allocate HTTP request structure

nng_http_req_copy_data(3http)

copy HTTP request body

nng_http_req_del_header(3http)

delete HTTP request header

nng_http_req_free(3http)

free HTTP request structure

nng_http_req_get_data(3http)

get HTTP request body

nng_http_req_get_header(3http)

return HTTP request header

nng_http_req_get_method(3http)

return HTTP request method

nng_http_req_get_uri(3http)

return HTTP request URI

nng_http_req_get_version(3http)

return HTTP request protocol version

nng_http_req_reset(3http)

reset HTTP request structure

nng_http_req_set_data(3http)

set HTTP request body

nng_http_req_set_header(3http)

set HTTP request header

nng_http_req_set_method(3http)

set HTTP request method

nng_http_req_set_uri(3http)

set HTTP request URI

nng_http_req_set_version(3http)

set HTTP request protocol version

nng_http_res_add_header(3http)

add HTTP response header

nng_http_res_alloc(3http)

allocate HTTP response structure

nng_http_res_alloc_error(3http)

allocate HTTP error response

nng_http_res_copy_data(3http)

copy HTTP response body

nng_http_res_del_header(3http)

delete HTTP response header

nng_http_res_free(3http)

free HTTP response structure

nng_http_res_get_data(3http)

get HTTP response body

nng_http_res_get_header(3http)

return HTTP response header

nng_http_res_get_reason(3http)

return HTTP response reason

nng_http_res_get_status(3http)

return HTTP status code

nng_http_res_get_version(3http)

return HTTP response protocol version

nng_http_res_reset(3http)

reset HTTP response structure

nng_http_res_set_data(3http)

set HTTP response body

nng_http_res_set_header(3http)

set HTTP response header

nng_http_res_set_reason(3http)

set HTTP response reason

nng_http_res_set_status(3http)

set HTTP response status

nng_http_res_set_version(3http)

set HTTP response protocol version

nng_http_server_add_handler(3http)

add HTTP server handler

nng_http_server_del_handler(3http)

delete HTTP server handler

nng_http_server_get_addr(3http)

get HTTP server address

nng_http_server_get_tls(3http)

get HTTP server TLS configuration

nng_http_server_hold(3http)

get and hold HTTP server instance

nng_http_server_release(3http)

release HTTP server instance

nng_http_server_res_error(3http)

use HTTP server error page

nng_http_server_set_error_file(3http)

set custom HTTP error file

nng_http_server_set_error_page(3http)

set custom HTTP error page

nng_http_server_set_tls(3http)

set HTTP server TLS configuration

nng_http_server_start(3http)

start HTTP server

nng_http_server_stop(3http)

stop HTTP server

Section 3str: Supplemental TCP Functions

This section documents supplemental byte stream functions that are available.

These functions are made available to facilitate using raw byte stream connections with the NNG asynchronous I/O API. These byte streams may be useful for applications that need to communicate with raw TCP/IP or IPC streams instead of Scalability Protocols.

nng_stream_close(3str)

close byte stream

nng_stream_dialer_alloc(3str)

allocate byte stream dialer

nng_stream_dialer_close(3str)

close byte stream dialer

nng_stream_dialer_dial(3str)

initiate outgoing byte stream connection

nng_stream_dialer_free(3str)

free byte stream dialer

nng_stream_dialer_get(3str)

get option from byte stream dialer

nng_stream_dialer_set(3str)

set option on byte stream dialer

nng_stream_free(3str)

free byte stream

nng_stream_get(3str)

get option from byte stream

nng_stream_listener_accept(3str)

accept incoming byte stream connection

nng_stream_listener_alloc(3str)

allocate byte stream listener

nng_stream_listener_close(3str)

close byte stream listener

nng_stream_listener_free(3str)

free byte stream listener

nng_stream_listener_get(3str)

get option from byte stream listener

nng_stream_listener_listen(3str)

bind listener to configured address

nng_stream_listener_set(3str)

set option on byte stream listener

nng_stream_recv(3str)

receive from byte stream

nng_stream_send(3str)

send to byte stream

nng_stream_set(3str)

set option on byte stream

Section 3supp: Supplemental Functions

This section documents supplemental functions that are available. These functions are not intrinsic to building Scalability Protocols applications with this library.

However, their use may facilitate writing portable applications by providing uniform functions for common application needs such as mutual exclusion locks, threading, time keeping, and similar needs.

nng_clock(3supp)

get time

nng_cv_alloc(3supp)

allocate condition variable

nng_cv_free(3supp)

free condition variable

nng_cv_until(3supp)

wait for condition or timeout

nng_cv_wait(3supp)

wait for condition

nng_cv_wake(3supp)

wake all waiters

nng_cv_wake1(3supp)

wake one waiter

nng_id_map(3supp)

identifier based mapping table

nng_msleep(3supp)

sleep milliseconds

nng_mtx_alloc(3supp)

allocate mutex

nng_mtx_free(3supp)

free mutex

nng_mtx_lock(3supp)

lock mutex

nng_mtx_unlock(3supp)

unlock mutex

nng_opts_parse(3supp)

parse command line options

nng_random(3supp)

get random number

nng_socket_pair(3supp)

create a connected pair of BSD sockets

nng_thread_create(3supp)

create thread

nng_thread_destroy(3supp)

reap thread

nng_thread_set_name(3supp)

set thread name

Section 3tls: Supplemental TLS Functions

This section documents supplemental TLS (Transport Layer Security) functions that are available. TLS support is available when using Scalability Protocols with the TLS transport, or when using WebSocket, either with the WebSocket transport for Scalability Protocols, or combined with other HTTP capabilities.

These functions depend on library support that is not included directly with NNG however, so their presence will depend on whether this additional support was present and enabled with libnng was built.

Currently, this extra support can be provided by the mbedTLS library or by external plug-ins.

Contact Staysail Systems, Inc. for details about commercially available options, including support for FIPS 140-2 validated cryptography and TLS v1.3.

nng_tls_config_alloc(3tls)

allocate TLS configuration object

nng_tls_config_auth_mode(3tls)

configure authentication mode

nng_tls_config_ca_chain(3tls)

configure certificate authority certificate chain

nng_tls_config_ca_file(3tls)

load certificate authority from file

nng_tls_config_cert_key_file(3tls)

load own certificate and key from file

nng_tls_config_free(3tls)

deallocate a TLS configuration object

nng_tls_config_hold(3tls)

hold TLS configuration object

nng_tls_config_own_cert(3tls)

configure own certificate and key

nng_tls_config_server_name(3tls)

configure remote server name

nng_tls_config_version(3tls)

configure TLS version

nng_tls_engine_description(3tls)

TLS engine description

nng_tls_engine_fips_mode(3tls)

TLS FIPS 140-2 mode indicator

nng_tls_engine_name(3tls)

TLS engine name

Section 5: Macros and Types

This section documents core macros and types that are available.

These are the core types and macros that most Scalabilty Protocols applications need will use.

nng_aio(5)

asynchronous I/O handle

nng_ctx(5)

protocol context

nng_dialer(5)

dialer

nng_duration(5)

relative time in milliseconds

nng_iov(5)

scatter/gather element

nng_ipc_options(5)

IPC-specific options

nng_listener(5)

listener

nng_msg(5)

message

nng_options(5)

socket, dialer, listener, and pipe options

nng_pipe(5)

communications pipe

nng_sockaddr(5)

socket address

nng_sockaddr_abstract(5)

abstract IPC socket address

nng_sockaddr_in(5)

IPv4 socket address

nng_sockaddr_in6(5)

IPv6 socket address

nng_sockaddr_inproc(5)

inproc socket address

nng_sockaddr_ipc(5)

IPC socket address

nng_sockaddr_zt(5)

ZeroTier socket address

nng_socket(5)

socket handle

nng_stat(5)

statistic

nng_stream(5)

byte stream

nng_stream_dialer(5)

byte stream dialer

nng_stream_listener(5)

byte stream listener

nng_tcp_options(5)

TCP-specific options

nng_tls_config(5)

TLS configuration object

nng_tls_engine(5)

TLS engine implementation

nng_tls_options(5)

TLS-specific options

nng_url(5)

Universal Resource Locator object

Section 7: Protocols and Transports

This sections documents various protocols and transports that are available in the distribution.

Protocols implement communication patterns, such as request/reply, publish/subscribe, and so forth. A given socket is created with exactly one protocol, and that protocol defines the key behavior of the socket.

Conversely, transports are the underlying mechansims by which messages are moved between participants, such as TCP/IP or UNIX domain IPC. A given socket may be using several transports at the same time.

nng(7)

nanomsg next generation

nng_bus(7)

bus protocol

nng_inproc(7)

intra-process transport

nng_ipc(7)

IPC transport

nng_pair(7)

pair protocol

nng_pub(7)

publisher protocol

nng_pull(7)

pull protocol

nng_push(7)

push protocol

nng_rep(7)

reply protocol

nng_req(7)

request protocol

nng_respondent(7)

respondent protocol

nng_socket(7)

BSD Socket transport (experimental)

nng_sub(7)

subscriber protocol

nng_surveyor(7)

surveyor protocol

nng_tcp(7)

TCP/IP transport

nng_tls(7)

TLS transport

nng_ws(7)

WebSocket transport

nng_zerotier(7)

ZeroTier transport