libnng(3)

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

nng_dial()

create and start dialer

nng_dialer_close()

close dialer

create dialer

get dialer option

get dialer option

get numeric dialer identifier

set dialer option

set dialer option

start dialer

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

nng_listener_id()

get numeric listener identifier

nng_listener_set()

set listener option

nng_listener_setopt()

set listener option

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

nng_pipe_id()

get numeric pipe identifier

nng_pipe_listener()

return listener that created pipe

nng_pipe_notify()

nng_pipe_socket()

return owning socket for pipe

Message Handling Functions

Applications desiring to use the richest part of libnng will want to +use the message API, where a message structure is passed between functions. +This API provides the most power support for zero-copy.

Messages are divided into a header and body, where the body generally carries +user-payload and the header carries protocol specific header information. +Most applications will only interact with the body.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

nng_msg_alloc()

allocate a message

nng_msg_append()

append to message body

nng_msg_body()

return message body

nng_msg_chop()

remove data from end of message body

clear message body

duplicate a message

free a message

get pipe for message

prepend to message body

nng_msg_len()

return the message body length

nng_msg_realloc()

reallocate a message

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

+ + + + + +

+ +	+Few applications will need these functions, as message headers are only +used to carry protocol-specific content. However, applications which use raw +mode may need to access the header of messages. +

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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

Most applications will interact with nng synchronously; that is that +functions such as nng_send() will block the calling +thread until the operation has completed.

+ + + + + +

+ +	+Synchronous operations which send messages may return before the +message has actually been received, or even transmitted. Instead, These +functions return as soon as the message was successfully queued for +delivery. +

Asynchronous operations behave differently. These operations are +initiated by the calling thread, but control returns immediately to +the calling thread. When the operation is subsequently completed (regardless +of whether this was successful or not), then a user supplied function +(“callback”) is executed.

A context structure, an nng_aio, is allocated and +associated with each asynchronous operation. +Only a single asynchronous operation may be associated with an +nng_aio at any time.

The following functions are used in the asynchronous model:

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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_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_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

The following functions are used to construct a socket with a specific protocol:

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

open a bus socket

open a pair socket

open a pub socket

open a pull socket

open a push socket

open a rep socket

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

Transports

The following functions are used to register a transport for use.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

nng_inproc_register()

Protocol Contexts

The following functions are useful to separate the protocol processing +from a socket object, into a separate context. +This can allow multiple contexts to be created on a single socket for +concurrent applications.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

close context

get context option

get context option

get numeric context identifier

nng_ctx_open()

create context

nng_ctx_recv()

receive message using context asynchronously

nng_ctx_send()

send message using context asynchronously

nng_ctx_set()

set context option

nng_ctx_setopt()

set context option

Statistics

The following functions provide access to statistics which can be used +to observe program behaviors and as an aid in troubleshooting.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

nng_stat_child()

get child statistic

nng_stat_name()

get statistic description

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

get statistic type

get statistic unit

get statistic value

free statistics

get statistics

URL Object

Common functionality is supplied for parsing and handling +universal resource locators (URLS).

+ ++++ + + + + + + + + + + + + + + +

nng_url_clone()

clone URL structure

nng_url_free()

free URL structure

nng_url_parse()

create URL structure from string

Supplemental API

These supplemental functions are not intrinsic to building +network applications with NNG, but they are made available +as a convenience to aid in creating portable applications.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

nng_clock()

get time

nng_cv_alloc()

allocate condition variable

nng_cv_free()

free condition variable

nng_cv_until()

wait for condition or timeout

wait for condition

wake all waiters

wake one waiter

sleep for milliseconds

allocate mutex

free mutex

lock mutex

unlock mutex

parse command line options

nng_random()

get random number

nng_thread_create()

create thread

nng_thread_destroy()

reap thread

Byte Streams

These functions are available for use with byte streams. +They are considered low-level, for uses where the higher level functions +using Scalability Protocols are inappropriate.

Byte streams, represented by +nng_stream objects, correspond to underlying +connections such as TCP connections or named pipes. +They are created by either +nng_stream_dialer or +nng_stream_listener objects.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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

The library may be configured with support for HTTP, and this will +be the case if WebSocket support is configured as well. +In this case, it is possible to access functionality to support the creation of +HTTP (and HTTP/S if TLS support is present) servers and clients.

Common HTTP Functions

The following functions are used to work with HTTP requests, responses, +and connections.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

nng_http_conn_close()

close HTTP connection

nng_http_conn_read()

read from HTTP connection

nng_http_conn_read_all()

read all from HTTP connection

nng_http_conn_read_req()

read HTTP request

nng_http_conn_read_res()

read HTTP response

nng_http_conn_write()

write to HTTP connection

nng_http_conn_write_all()

write all to HTTP connection

nng_http_conn_write_req()

write HTTP request

nng_http_conn_write_res()

write HTTP response

nng_http_req_add_header()

add HTTP request header

nng_http_req_alloc()

allocate HTTP request structure

nng_http_req_copy_data()

copy HTTP request body

nng_http_req_del_header()

delete HTTP request header

nng_http_req_free()

free HTTP request structure

nng_http_req_get_data()

get HTTP request body

nng_http_req_get_header()

return HTTP request header

nng_http_req_get_method()

return HTTP request method

nng_http_req_get_uri()

return HTTP request URI

nng_http_req_get_version()

return HTTP request protocol version

nng_http_req_reset()

reset HTTP request structure

nng_http_req_set_data()

set HTTP request body

nng_http_req_set_header()

set HTTP request header

nng_http_req_set_method()

set HTTP request method

nng_http_req_set_uri()

set HTTP request URI

nng_http_req_set_version()

set HTTP request protocol version

nng_http_res_add_header()

add HTTP response header

nng_http_res_alloc()

allocate HTTP response structure

nng_http_res_alloc_error()

allocate HTTP error response

nng_http_res_copy_data()

copy HTTP response body

nng_http_res_del_header()

delete HTTP response header

nng_http_res_free()

free HTTP response structure

nng_http_res_get_data()

get HTTP response body

nng_http_res_get_header()

return HTTP response header

nng_http_res_get_reason()

return HTTP response reason

nng_http_res_get_status()

return HTTP response status

nng_http_res_get_version()

return HTTP response protocol version

nng_http_res_reset()

reset HTTP response structure

nng_http_res_set_data()

set HTTP response body

nng_http_res_set_header()

set HTTP response header

nng_http_res_set_reason()

set HTTP response reason

nng_http_res_set_status()

set HTTP response status

nng_http_res_set_version()

set HTTP response protocol version

HTTP Client Functions

These functions are intended for use with HTTP client applications.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

nng_http_client_alloc()

allocate HTTP client

nng_http_client_connect()

establish HTTP client connection

nng_http_client_free()

free HTTP client

nng_http_client_get_tls()

get HTTP client TLS configuration

nng_http_client_set_tls()

set HTTP client TLS configuration

nng_http_client_transact()

perform one HTTP transaction

nng_http_conn_transact()

perform one HTTP transaction on connection

HTTP Server Functions

These functions are intended for use with HTTP server applications.

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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_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. Most of these functions will not be used even +by TLS applications.

+ + + + + +

+ +	+These functions will only be present if the library has been built +with TLS support. +

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

nng_tls_close()

close TLS connection

nng_tls_config_alloc()

allocate TLS configuration

nng_tls_config_auth_mode()

set authentication mode

nng_tls_config_ca_chain()

set certificate authority chain

nng_tls_config_ca_file()

load certificate authority from file

nng_tls_config_cert_key_file()

load own certificate and key from file

nng_tls_config_own_cert()

set own certificate and key

nng_tls_config_free()

free TLS configuration

nng_tls_config_server_name()

set remote server name

nng_tls_dialer_alloc()

allocate TLS dialer

nng_tls_dialer_close()

close TLS dialer

nng_tls_dialer_dial()

initiate outgoing TLS connection

nng_tls_dialer_free()

free TLS dialer

nng_tls_dialer_getopt()

get option from TLS dialer

nng_tls_dialer_setopt()

set option on TLS dialer

nng_tls_free()

free TLS connection

nng_tls_getopt()

get option from TLS connection

nng_tls_listener_accept()

accept incoming TLS connection

nng_tls_listener_alloc()

allocate TLS listener

nng_tls_listener_close()

close TLS listener

nng_tls_listener_free()

free TLS listener

nng_tls_listener_getopt()

get option from TLS listener

nng_tls_listener_listen()

bind TLS listener to port

nng_tls_listener_setopt()

set option on TLS listener

nng_tls_recv()

receive from TLS connection

nng_tls_send()

send to TLS connection

nng_tls_setopt()

set option on TLS connection

libnng(3) Manual Page

NAME

SYNOPSIS

DESCRIPTION

Common Functions

Socket Functions

Connection Management

Message Handling Functions

Message Header Handling

Asynchronous Operations

Protocols

Transports

Protocol Contexts

Statistics

URL Object

Supplemental API

Byte Streams

HTTP Support

Common HTTP Functions

HTTP Client Functions

HTTP Server Functions

TLS Configuration Objects

SEE ALSO