diff options
| author | Staysail Systems, Inc <info@staysail.tech> | 2024-02-22 01:03:04 -0800 |
|---|---|---|
| committer | Garrett D'Amore <garrett@damore.org> | 2024-02-22 01:04:43 -0800 |
| commit | d7a4a138ba371e8a969a7fde8219c88870d288fc (patch) | |
| tree | 99a2f036788e66570b38d2b20923945bc941946a | |
| parent | e96b0be664b5c67cc13898864d46fdb5956de1b1 (diff) | |
| download | nng-d7a4a138ba371e8a969a7fde8219c88870d288fc.tar.gz nng-d7a4a138ba371e8a969a7fde8219c88870d288fc.tar.bz2 nng-d7a4a138ba371e8a969a7fde8219c88870d288fc.zip | |
Manual page updates for v1.7.2
327 files changed, 45096 insertions, 0 deletions
diff --git a/man/v1.7.2/_toc.html b/man/v1.7.2/_toc.html new file mode 100644 index 00000000..505d9a16 --- /dev/null +++ b/man/v1.7.2/_toc.html @@ -0,0 +1,367 @@ +<nav id="toc" class="toc2"> +<div id="toctitle">Table of Contents</div> +<ul class="sectlevel1 +"> +<li>Commands and Utilities +</li> +<ul class="sectlevel2"> +<li><a href="nngcat.1.html">nngcat</a></li> +</ul> +<li>Library Functions +</li> +<ul class="sectlevel2"> +<li><a href="libnng.3.html">libnng</a></li> +<li><a href="nng_aio_abort.3.html">nng_aio_abort</a></li> +<li><a href="nng_aio_alloc.3.html">nng_aio_alloc</a></li> +<li><a href="nng_aio_begin.3.html">nng_aio_begin</a></li> +<li><a href="nng_aio_busy.3.html">nng_aio_busy</a></li> +<li><a href="nng_aio_cancel.3.html">nng_aio_cancel</a></li> +<li><a href="nng_aio_count.3.html">nng_aio_count</a></li> +<li><a href="nng_aio_defer.3.html">nng_aio_defer</a></li> +<li><a href="nng_aio_finish.3.html">nng_aio_finish</a></li> +<li><a href="nng_aio_free.3.html">nng_aio_free</a></li> +<li><a href="nng_aio_get_input.3.html">nng_aio_get_input</a></li> +<li><a href="nng_aio_get_msg.3.html">nng_aio_get_msg</a></li> +<li><a href="nng_aio_get_output.3.html">nng_aio_get_output</a></li> +<li><a href="nng_aio_result.3.html">nng_aio_result</a></li> +<li><a href="nng_aio_set_input.3.html">nng_aio_set_input</a></li> +<li><a href="nng_aio_set_iov.3.html">nng_aio_set_iov</a></li> +<li><a href="nng_aio_set_msg.3.html">nng_aio_set_msg</a></li> +<li><a href="nng_aio_set_output.3.html">nng_aio_set_output</a></li> +<li><a href="nng_aio_set_timeout.3.html">nng_aio_set_timeout</a></li> +<li><a href="nng_aio_stop.3.html">nng_aio_stop</a></li> +<li><a href="nng_aio_wait.3.html">nng_aio_wait</a></li> +<li><a href="nng_alloc.3.html">nng_alloc</a></li> +<li><a href="nng_bus_open.3.html">nng_bus_open</a></li> +<li><a href="nng_close.3.html">nng_close</a></li> +<li><a href="nng_ctx_close.3.html">nng_ctx_close</a></li> +<li><a href="nng_ctx_get.3.html">nng_ctx_get</a></li> +<li><a href="nng_ctx_getopt.3.html">nng_ctx_getopt</a></li> +<li><a href="nng_ctx_id.3.html">nng_ctx_id</a></li> +<li><a href="nng_ctx_open.3.html">nng_ctx_open</a></li> +<li><a href="nng_ctx_recv.3.html">nng_ctx_recv</a></li> +<li><a href="nng_ctx_recvmsg.3.html">nng_ctx_recvmsg</a></li> +<li><a href="nng_ctx_send.3.html">nng_ctx_send</a></li> +<li><a href="nng_ctx_sendmsg.3.html">nng_ctx_sendmsg</a></li> +<li><a href="nng_ctx_set.3.html">nng_ctx_set</a></li> +<li><a href="nng_ctx_setopt.3.html">nng_ctx_setopt</a></li> +<li><a href="nng_device.3.html">nng_device</a></li> +<li><a href="nng_dial.3.html">nng_dial</a></li> +<li><a href="nng_dialer_close.3.html">nng_dialer_close</a></li> +<li><a href="nng_dialer_create.3.html">nng_dialer_create</a></li> +<li><a href="nng_dialer_get.3.html">nng_dialer_get</a></li> +<li><a href="nng_dialer_getopt.3.html">nng_dialer_getopt</a></li> +<li><a href="nng_dialer_id.3.html">nng_dialer_id</a></li> +<li><a href="nng_dialer_set.3.html">nng_dialer_set</a></li> +<li><a href="nng_dialer_setopt.3.html">nng_dialer_setopt</a></li> +<li><a href="nng_dialer_start.3.html">nng_dialer_start</a></li> +<li><a href="nng_free.3.html">nng_free</a></li> +<li><a href="nng_getopt.3.html">nng_getopt</a></li> +<li><a href="nng_inproc_register.3.html">nng_inproc_register</a></li> +<li><a href="nng_ipc_register.3.html">nng_ipc_register</a></li> +<li><a href="nng_listen.3.html">nng_listen</a></li> +<li><a href="nng_listener_close.3.html">nng_listener_close</a></li> +<li><a href="nng_listener_create.3.html">nng_listener_create</a></li> +<li><a href="nng_listener_get.3.html">nng_listener_get</a></li> +<li><a href="nng_listener_getopt.3.html">nng_listener_getopt</a></li> +<li><a href="nng_listener_id.3.html">nng_listener_id</a></li> +<li><a href="nng_listener_set.3.html">nng_listener_set</a></li> +<li><a href="nng_listener_setopt.3.html">nng_listener_setopt</a></li> +<li><a href="nng_listener_start.3.html">nng_listener_start</a></li> +<li><a href="nng_msg_alloc.3.html">nng_msg_alloc</a></li> +<li><a href="nng_msg_append.3.html">nng_msg_append</a></li> +<li><a href="nng_msg_body.3.html">nng_msg_body</a></li> +<li><a href="nng_msg_capacity.3.html">nng_msg_capacity</a></li> +<li><a href="nng_msg_chop.3.html">nng_msg_chop</a></li> +<li><a href="nng_msg_clear.3.html">nng_msg_clear</a></li> +<li><a href="nng_msg_dup.3.html">nng_msg_dup</a></li> +<li><a href="nng_msg_free.3.html">nng_msg_free</a></li> +<li><a href="nng_msg_get_pipe.3.html">nng_msg_get_pipe</a></li> +<li><a href="nng_msg_header.3.html">nng_msg_header</a></li> +<li><a href="nng_msg_header_append.3.html">nng_msg_header_append</a></li> +<li><a href="nng_msg_header_chop.3.html">nng_msg_header_chop</a></li> +<li><a href="nng_msg_header_clear.3.html">nng_msg_header_clear</a></li> +<li><a href="nng_msg_header_insert.3.html">nng_msg_header_insert</a></li> +<li><a href="nng_msg_header_len.3.html">nng_msg_header_len</a></li> +<li><a href="nng_msg_header_trim.3.html">nng_msg_header_trim</a></li> +<li><a href="nng_msg_insert.3.html">nng_msg_insert</a></li> +<li><a href="nng_msg_len.3.html">nng_msg_len</a></li> +<li><a href="nng_msg_realloc.3.html">nng_msg_realloc</a></li> +<li><a href="nng_msg_reserve.3.html">nng_msg_reserve</a></li> +<li><a href="nng_msg_set_pipe.3.html">nng_msg_set_pipe</a></li> +<li><a href="nng_msg_trim.3.html">nng_msg_trim</a></li> +<li><a href="nng_pair_open.3.html">nng_pair_open</a></li> +<li><a href="nng_pipe_close.3.html">nng_pipe_close</a></li> +<li><a href="nng_pipe_dialer.3.html">nng_pipe_dialer</a></li> +<li><a href="nng_pipe_get.3.html">nng_pipe_get</a></li> +<li><a href="nng_pipe_getopt.3.html">nng_pipe_getopt</a></li> +<li><a href="nng_pipe_id.3.html">nng_pipe_id</a></li> +<li><a href="nng_pipe_listener.3.html">nng_pipe_listener</a></li> +<li><a href="nng_pipe_notify.3.html">nng_pipe_notify</a></li> +<li><a href="nng_pipe_socket.3.html">nng_pipe_socket</a></li> +<li><a href="nng_pub_open.3.html">nng_pub_open</a></li> +<li><a href="nng_pull_open.3.html">nng_pull_open</a></li> +<li><a href="nng_push_open.3.html">nng_push_open</a></li> +<li><a href="nng_recv.3.html">nng_recv</a></li> +<li><a href="nng_recv_aio.3.html">nng_recv_aio</a></li> +<li><a href="nng_recvmsg.3.html">nng_recvmsg</a></li> +<li><a href="nng_rep_open.3.html">nng_rep_open</a></li> +<li><a href="nng_req_open.3.html">nng_req_open</a></li> +<li><a href="nng_respondent_open.3.html">nng_respondent_open</a></li> +<li><a href="nng_send.3.html">nng_send</a></li> +<li><a href="nng_send_aio.3.html">nng_send_aio</a></li> +<li><a href="nng_sendmsg.3.html">nng_sendmsg</a></li> +<li><a href="nng_setopt.3.html">nng_setopt</a></li> +<li><a href="nng_sleep_aio.3.html">nng_sleep_aio</a></li> +<li><a href="nng_socket_get.3.html">nng_socket_get</a></li> +<li><a href="nng_socket_id.3.html">nng_socket_id</a></li> +<li><a href="nng_socket_set.3.html">nng_socket_set</a></li> +<li><a href="nng_stat_bool.3.html">nng_stat_bool</a></li> +<li><a href="nng_stat_child.3.html">nng_stat_child</a></li> +<li><a href="nng_stat_desc.3.html">nng_stat_desc</a></li> +<li><a href="nng_stat_find.3.html">nng_stat_find</a></li> +<li><a href="nng_stat_find_dialer.3.html">nng_stat_find_dialer</a></li> +<li><a href="nng_stat_find_listener.3.html">nng_stat_find_listener</a></li> +<li><a href="nng_stat_find_socket.3.html">nng_stat_find_socket</a></li> +<li><a href="nng_stat_name.3.html">nng_stat_name</a></li> +<li><a href="nng_stat_next.3.html">nng_stat_next</a></li> +<li><a href="nng_stat_string.3.html">nng_stat_string</a></li> +<li><a href="nng_stat_timestamp.3.html">nng_stat_timestamp</a></li> +<li><a href="nng_stat_type.3.html">nng_stat_type</a></li> +<li><a href="nng_stat_unit.3.html">nng_stat_unit</a></li> +<li><a href="nng_stat_value.3.html">nng_stat_value</a></li> +<li><a href="nng_stats_free.3.html">nng_stats_free</a></li> +<li><a href="nng_stats_get.3.html">nng_stats_get</a></li> +<li><a href="nng_strdup.3.html">nng_strdup</a></li> +<li><a href="nng_strerror.3.html">nng_strerror</a></li> +<li><a href="nng_strfree.3.html">nng_strfree</a></li> +<li><a href="nng_sub_open.3.html">nng_sub_open</a></li> +<li><a href="nng_surveyor_open.3.html">nng_surveyor_open</a></li> +<li><a href="nng_tcp_register.3.html">nng_tcp_register</a></li> +<li><a href="nng_tls_register.3.html">nng_tls_register</a></li> +<li><a href="nng_url_clone.3.html">nng_url_clone</a></li> +<li><a href="nng_url_free.3.html">nng_url_free</a></li> +<li><a href="nng_url_parse.3.html">nng_url_parse</a></li> +<li><a href="nng_version.3.html">nng_version</a></li> +<li><a href="nng_ws_register.3.html">nng_ws_register</a></li> +<li><a href="nng_wss_register.3.html">nng_wss_register</a></li> +<li><a href="nng_zt_register.3.html">nng_zt_register</a></li> +</ul> +<li>Compatible Library Functions +</li> +<ul class="sectlevel2"> +<li><a href="nn_allocmsg.3compat.html">nn_allocmsg</a></li> +<li><a href="nn_bind.3compat.html">nn_bind</a></li> +<li><a href="nn_close.3compat.html">nn_close</a></li> +<li><a href="nn_cmsg.3compat.html">nn_cmsg</a></li> +<li><a href="nn_connect.3compat.html">nn_connect</a></li> +<li><a href="nn_device.3compat.html">nn_device</a></li> +<li><a href="nn_errno.3compat.html">nn_errno</a></li> +<li><a href="nn_freemsg.3compat.html">nn_freemsg</a></li> +<li><a href="nn_get_statistic.3compat.html">nn_get_statistic</a></li> +<li><a href="nn_getsockopt.3compat.html">nn_getsockopt</a></li> +<li><a href="nn_poll.3compat.html">nn_poll</a></li> +<li><a href="nn_reallocmsg.3compat.html">nn_reallocmsg</a></li> +<li><a href="nn_recv.3compat.html">nn_recv</a></li> +<li><a href="nn_recvmsg.3compat.html">nn_recvmsg</a></li> +<li><a href="nn_send.3compat.html">nn_send</a></li> +<li><a href="nn_sendmsg.3compat.html">nn_sendmsg</a></li> +<li><a href="nn_setsockopt.3compat.html">nn_setsockopt</a></li> +<li><a href="nn_shutdown.3compat.html">nn_shutdown</a></li> +<li><a href="nn_socket.3compat.html">nn_socket</a></li> +<li><a href="nn_strerror.3compat.html">nn_strerror</a></li> +<li><a href="nn_term.3compat.html">nn_term</a></li> +<li><a href="nng_compat.3compat.html">nng_compat</a></li> +</ul> +<li>Supplemental HTTP Functions +</li> +<ul class="sectlevel2"> +<li><a href="nng_http_client_alloc.3http.html">nng_http_client_alloc</a></li> +<li><a href="nng_http_client_connect.3http.html">nng_http_client_connect</a></li> +<li><a href="nng_http_client_free.3http.html">nng_http_client_free</a></li> +<li><a href="nng_http_client_get_tls.3http.html">nng_http_client_get_tls</a></li> +<li><a href="nng_http_client_set_tls.3http.html">nng_http_client_set_tls</a></li> +<li><a href="nng_http_client_transact.3http.html">nng_http_client_transact</a></li> +<li><a href="nng_http_conn_close.3http.html">nng_http_conn_close</a></li> +<li><a href="nng_http_conn_read.3http.html">nng_http_conn_read</a></li> +<li><a href="nng_http_conn_read_all.3http.html">nng_http_conn_read_all</a></li> +<li><a href="nng_http_conn_read_req.3http.html">nng_http_conn_read_req</a></li> +<li><a href="nng_http_conn_read_res.3http.html">nng_http_conn_read_res</a></li> +<li><a href="nng_http_conn_transact.3http.html">nng_http_conn_transact</a></li> +<li><a href="nng_http_conn_write.3http.html">nng_http_conn_write</a></li> +<li><a href="nng_http_conn_write_all.3http.html">nng_http_conn_write_all</a></li> +<li><a href="nng_http_conn_write_req.3http.html">nng_http_conn_write_req</a></li> +<li><a href="nng_http_conn_write_res.3http.html">nng_http_conn_write_res</a></li> +<li><a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc</a></li> +<li><a href="nng_http_handler_collect_body.3http.html">nng_http_handler_collect_body</a></li> +<li><a href="nng_http_handler_free.3http.html">nng_http_handler_free</a></li> +<li><a href="nng_http_handler_get_data.3http.html">nng_http_handler_get_data</a></li> +<li><a href="nng_http_handler_set_data.3http.html">nng_http_handler_set_data</a></li> +<li><a href="nng_http_handler_set_host.3http.html">nng_http_handler_set_host</a></li> +<li><a href="nng_http_handler_set_method.3http.html">nng_http_handler_set_method</a></li> +<li><a href="nng_http_handler_set_tree.3http.html">nng_http_handler_set_tree</a></li> +<li><a href="nng_http_hijack.3http.html">nng_http_hijack</a></li> +<li><a href="nng_http_req_add_header.3http.html">nng_http_req_add_header</a></li> +<li><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc</a></li> +<li><a href="nng_http_req_copy_data.3http.html">nng_http_req_copy_data</a></li> +<li><a href="nng_http_req_del_header.3http.html">nng_http_req_del_header</a></li> +<li><a href="nng_http_req_free.3http.html">nng_http_req_free</a></li> +<li><a href="nng_http_req_get_data.3http.html">nng_http_req_get_data</a></li> +<li><a href="nng_http_req_get_header.3http.html">nng_http_req_get_header</a></li> +<li><a href="nng_http_req_get_method.3http.html">nng_http_req_get_method</a></li> +<li><a href="nng_http_req_get_uri.3http.html">nng_http_req_get_uri</a></li> +<li><a href="nng_http_req_get_version.3http.html">nng_http_req_get_version</a></li> +<li><a href="nng_http_req_reset.3http.html">nng_http_req_reset</a></li> +<li><a href="nng_http_req_set_data.3http.html">nng_http_req_set_data</a></li> +<li><a href="nng_http_req_set_header.3http.html">nng_http_req_set_header</a></li> +<li><a href="nng_http_req_set_method.3http.html">nng_http_req_set_method</a></li> +<li><a href="nng_http_req_set_uri.3http.html">nng_http_req_set_uri</a></li> +<li><a href="nng_http_req_set_version.3http.html">nng_http_req_set_version</a></li> +<li><a href="nng_http_res_add_header.3http.html">nng_http_res_add_header</a></li> +<li><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc</a></li> +<li><a href="nng_http_res_alloc_error.3http.html">nng_http_res_alloc_error</a></li> +<li><a href="nng_http_res_copy_data.3http.html">nng_http_res_copy_data</a></li> +<li><a href="nng_http_res_del_header.3http.html">nng_http_res_del_header</a></li> +<li><a href="nng_http_res_free.3http.html">nng_http_res_free</a></li> +<li><a href="nng_http_res_get_data.3http.html">nng_http_res_get_data</a></li> +<li><a href="nng_http_res_get_header.3http.html">nng_http_res_get_header</a></li> +<li><a href="nng_http_res_get_reason.3http.html">nng_http_res_get_reason</a></li> +<li><a href="nng_http_res_get_status.3http.html">nng_http_res_get_status</a></li> +<li><a href="nng_http_res_get_version.3http.html">nng_http_res_get_version</a></li> +<li><a href="nng_http_res_reset.3http.html">nng_http_res_reset</a></li> +<li><a href="nng_http_res_set_data.3http.html">nng_http_res_set_data</a></li> +<li><a href="nng_http_res_set_header.3http.html">nng_http_res_set_header</a></li> +<li><a href="nng_http_res_set_reason.3http.html">nng_http_res_set_reason</a></li> +<li><a href="nng_http_res_set_status.3http.html">nng_http_res_set_status</a></li> +<li><a href="nng_http_res_set_version.3http.html">nng_http_res_set_version</a></li> +<li><a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler</a></li> +<li><a href="nng_http_server_del_handler.3http.html">nng_http_server_del_handler</a></li> +<li><a href="nng_http_server_get_addr.3http.html">nng_http_server_get_addr</a></li> +<li><a href="nng_http_server_get_tls.3http.html">nng_http_server_get_tls</a></li> +<li><a href="nng_http_server_hold.3http.html">nng_http_server_hold</a></li> +<li><a href="nng_http_server_release.3http.html">nng_http_server_release</a></li> +<li><a href="nng_http_server_res_error.3http.html">nng_http_server_res_error</a></li> +<li><a href="nng_http_server_set_error_file.3http.html">nng_http_server_set_error_file</a></li> +<li><a href="nng_http_server_set_error_page.3http.html">nng_http_server_set_error_page</a></li> +<li><a href="nng_http_server_set_tls.3http.html">nng_http_server_set_tls</a></li> +<li><a href="nng_http_server_start.3http.html">nng_http_server_start</a></li> +<li><a href="nng_http_server_stop.3http.html">nng_http_server_stop</a></li> +</ul> +<li>Supplemental TCP Functions +</li> +<ul class="sectlevel2"> +<li><a href="nng_stream_close.3str.html">nng_stream_close</a></li> +<li><a href="nng_stream_dialer_alloc.3str.html">nng_stream_dialer_alloc</a></li> +<li><a href="nng_stream_dialer_close.3str.html">nng_stream_dialer_close</a></li> +<li><a href="nng_stream_dialer_dial.3str.html">nng_stream_dialer_dial</a></li> +<li><a href="nng_stream_dialer_free.3str.html">nng_stream_dialer_free</a></li> +<li><a href="nng_stream_dialer_get.3str.html">nng_stream_dialer_get</a></li> +<li><a href="nng_stream_dialer_set.3str.html">nng_stream_dialer_set</a></li> +<li><a href="nng_stream_free.3str.html">nng_stream_free</a></li> +<li><a href="nng_stream_get.3str.html">nng_stream_get</a></li> +<li><a href="nng_stream_listener_accept.3str.html">nng_stream_listener_accept</a></li> +<li><a href="nng_stream_listener_alloc.3str.html">nng_stream_listener_alloc</a></li> +<li><a href="nng_stream_listener_close.3str.html">nng_stream_listener_close</a></li> +<li><a href="nng_stream_listener_free.3str.html">nng_stream_listener_free</a></li> +<li><a href="nng_stream_listener_get.3str.html">nng_stream_listener_get</a></li> +<li><a href="nng_stream_listener_listen.3str.html">nng_stream_listener_listen</a></li> +<li><a href="nng_stream_listener_set.3str.html">nng_stream_listener_set</a></li> +<li><a href="nng_stream_recv.3str.html">nng_stream_recv</a></li> +<li><a href="nng_stream_send.3str.html">nng_stream_send</a></li> +<li><a href="nng_stream_set.3str.html">nng_stream_set</a></li> +</ul> +<li>Supplemental Functions +</li> +<ul class="sectlevel2"> +<li><a href="nng_clock.3supp.html">nng_clock</a></li> +<li><a href="nng_cv_alloc.3supp.html">nng_cv_alloc</a></li> +<li><a href="nng_cv_free.3supp.html">nng_cv_free</a></li> +<li><a href="nng_cv_until.3supp.html">nng_cv_until</a></li> +<li><a href="nng_cv_wait.3supp.html">nng_cv_wait</a></li> +<li><a href="nng_cv_wake.3supp.html">nng_cv_wake</a></li> +<li><a href="nng_cv_wake1.3supp.html">nng_cv_wake1</a></li> +<li><a href="nng_id_map.3supp.html">nng_id_map</a></li> +<li><a href="nng_msleep.3supp.html">nng_msleep</a></li> +<li><a href="nng_mtx_alloc.3supp.html">nng_mtx_alloc</a></li> +<li><a href="nng_mtx_free.3supp.html">nng_mtx_free</a></li> +<li><a href="nng_mtx_lock.3supp.html">nng_mtx_lock</a></li> +<li><a href="nng_mtx_unlock.3supp.html">nng_mtx_unlock</a></li> +<li><a href="nng_opts_parse.3supp.html">nng_opts_parse</a></li> +<li><a href="nng_random.3supp.html">nng_random</a></li> +<li><a href="nng_socket_pair.3supp.html">nng_socket_pair</a></li> +<li><a href="nng_thread_create.3supp.html">nng_thread_create</a></li> +<li><a href="nng_thread_destroy.3supp.html">nng_thread_destroy</a></li> +<li><a href="nng_thread_set_name.3supp.html">nng_thread_set_name</a></li> +</ul> +<li>Supplemental TLS Functions +</li> +<ul class="sectlevel2"> +<li><a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc</a></li> +<li><a href="nng_tls_config_auth_mode.3tls.html">nng_tls_config_auth_mode</a></li> +<li><a href="nng_tls_config_ca_chain.3tls.html">nng_tls_config_ca_chain</a></li> +<li><a href="nng_tls_config_ca_file.3tls.html">nng_tls_config_ca_file</a></li> +<li><a href="nng_tls_config_cert_key_file.3tls.html">nng_tls_config_cert_key_file</a></li> +<li><a href="nng_tls_config_free.3tls.html">nng_tls_config_free</a></li> +<li><a href="nng_tls_config_hold.3tls.html">nng_tls_config_hold</a></li> +<li><a href="nng_tls_config_own_cert.3tls.html">nng_tls_config_own_cert</a></li> +<li><a href="nng_tls_config_server_name.3tls.html">nng_tls_config_server_name</a></li> +<li><a href="nng_tls_config_version.3tls.html">nng_tls_config_version</a></li> +<li><a href="nng_tls_engine_description.3tls.html">nng_tls_engine_description</a></li> +<li><a href="nng_tls_engine_fips_mode.3tls.html">nng_tls_engine_fips_mode</a></li> +<li><a href="nng_tls_engine_name.3tls.html">nng_tls_engine_name</a></li> +</ul> +<li>Macros and Types +</li> +<ul class="sectlevel2"> +<li><a href="nng_aio.5.html">nng_aio</a></li> +<li><a href="nng_ctx.5.html">nng_ctx</a></li> +<li><a href="nng_dialer.5.html">nng_dialer</a></li> +<li><a href="nng_duration.5.html">nng_duration</a></li> +<li><a href="nng_iov.5.html">nng_iov</a></li> +<li><a href="nng_ipc_options.5.html">nng_ipc_options</a></li> +<li><a href="nng_listener.5.html">nng_listener</a></li> +<li><a href="nng_msg.5.html">nng_msg</a></li> +<li><a href="nng_options.5.html">nng_options</a></li> +<li><a href="nng_pipe.5.html">nng_pipe</a></li> +<li><a href="nng_sockaddr.5.html">nng_sockaddr</a></li> +<li><a href="nng_sockaddr_abstract.5.html">nng_sockaddr_abstract</a></li> +<li><a href="nng_sockaddr_in.5.html">nng_sockaddr_in</a></li> +<li><a href="nng_sockaddr_in6.5.html">nng_sockaddr_in6</a></li> +<li><a href="nng_sockaddr_inproc.5.html">nng_sockaddr_inproc</a></li> +<li><a href="nng_sockaddr_ipc.5.html">nng_sockaddr_ipc</a></li> +<li><a href="nng_sockaddr_zt.5.html">nng_sockaddr_zt</a></li> +<li><a href="nng_socket.5.html">nng_socket</a></li> +<li><a href="nng_stat.5.html">nng_stat</a></li> +<li><a href="nng_stream.5.html">nng_stream</a></li> +<li><a href="nng_stream_dialer.5.html">nng_stream_dialer</a></li> +<li><a href="nng_stream_listener.5.html">nng_stream_listener</a></li> +<li><a href="nng_tcp_options.5.html">nng_tcp_options</a></li> +<li><a href="nng_tls_config.5.html">nng_tls_config</a></li> +<li><a href="nng_tls_engine.5.html">nng_tls_engine</a></li> +<li><a href="nng_tls_options.5.html">nng_tls_options</a></li> +<li><a href="nng_url.5.html">nng_url</a></li> +</ul> +<li>Protocols and Transports +</li> +<ul class="sectlevel2"> +<li><a href="nng.7.html">nng</a></li> +<li><a href="nng_bus.7.html">nng_bus</a></li> +<li><a href="nng_inproc.7.html">nng_inproc</a></li> +<li><a href="nng_ipc.7.html">nng_ipc</a></li> +<li><a href="nng_pair.7.html">nng_pair</a></li> +<li><a href="nng_pub.7.html">nng_pub</a></li> +<li><a href="nng_pull.7.html">nng_pull</a></li> +<li><a href="nng_push.7.html">nng_push</a></li> +<li><a href="nng_rep.7.html">nng_rep</a></li> +<li><a href="nng_req.7.html">nng_req</a></li> +<li><a href="nng_respondent.7.html">nng_respondent</a></li> +<li><a href="nng_socket.7.html">nng_socket</a></li> +<li><a href="nng_sub.7.html">nng_sub</a></li> +<li><a href="nng_surveyor.7.html">nng_surveyor</a></li> +<li><a href="nng_tcp.7.html">nng_tcp</a></li> +<li><a href="nng_tls.7.html">nng_tls</a></li> +<li><a href="nng_ws.7.html">nng_ws</a></li> +<li><a href="nng_zerotier.7.html">nng_zerotier</a></li> +</ul> +</ul> +</nav> diff --git a/man/v1.7.2/index.html b/man/v1.7.2/index.html new file mode 100644 index 00000000..c0cdc222 --- /dev/null +++ b/man/v1.7.2/index.html @@ -0,0 +1,1564 @@ +--- +version: v1.7.2 +layout: manpage_v2 +--- +<h1>NNG Reference Manual</h1> +<div class="sect1"> +<h2 id="_section_1_commands_and_utilities">Section 1: Commands and Utilities</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This section documents utilities and programs that are included +with the distribution.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 37.5%;"> +<col style="width: 62.5%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nngcat.1.html">nngcat(1)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">command line access to Scalability Protocols</p></td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="sect1"> +<h2 id="_section_3_library_functions">Section 3: Library Functions</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This section documents core libary functions supporting Scalability +Protocols.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 37.5%;"> +<col style="width: 62.5%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="libnng.3.html">libnng(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">nanomsg next generation library</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_abort.3.html">nng_aio_abort(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">abort asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate asynchronous I/O handle</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_begin.3.html">nng_aio_begin(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">begin asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_busy.3.html">nng_aio_busy(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">test if asynchronous I/O is busy</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_cancel.3.html">nng_aio_cancel(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">cancel asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_count.3.html">nng_aio_count(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return number of bytes transferred</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_defer.3.html">nng_aio_defer(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">defer asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_finish.3.html">nng_aio_finish(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">finish asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_free.3.html">nng_aio_free(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free asynchronous I/O handle</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_get_input.3.html">nng_aio_get_input(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return input parameter</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_get_msg.3.html">nng_aio_get_msg(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get message from asynchronous receive</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_get_output.3.html">nng_aio_get_output(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return output result</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_result.3.html">nng_aio_result(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return result of asynchronous operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_set_input.3.html">nng_aio_set_input(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set input parameter</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_set_iov.3.html">nng_aio_set_iov(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set scatter/gather vector</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_set_msg.3.html">nng_aio_set_msg(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set message for asynchronous send</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_set_output.3.html">nng_aio_set_output(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set output result</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_set_timeout.3.html">nng_aio_set_timeout(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set asynchronous I/O timeout</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_stop.3.html">nng_aio_stop(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">stop asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_wait.3.html">nng_aio_wait(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">wait for asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_alloc.3.html">nng_alloc(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate memory</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_bus_open.3.html">nng_bus_open(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create bus socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_close.3.html">nng_close(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_close.3.html">nng_ctx_close(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close context</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_get.3.html">nng_ctx_get(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get context option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_getopt.3.html">nng_ctx_getopt(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get context option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_id.3.html">nng_ctx_id(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return numeric context identifier</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_open.3.html">nng_ctx_open(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create context</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_recv.3.html">nng_ctx_recv(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive message using context asynchronously</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_recvmsg.3.html">nng_ctx_recvmsg(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive message using socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_send.3.html">nng_ctx_send(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send message using context asynchronously</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_sendmsg.3.html">nng_ctx_sendmsg(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send message using context</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_set.3.html">nng_ctx_set(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set context option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_setopt.3.html">nng_ctx_setopt(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set context option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_device.3.html">nng_device(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">message forwarding device</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dial.3.html">nng_dial(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create and start dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_close.3.html">nng_dialer_close(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_create.3.html">nng_dialer_create(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_get.3.html">nng_dialer_get(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get dialer option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_getopt.3.html">nng_dialer_getopt(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get dialer option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_id.3.html">nng_dialer_id(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return numeric dialer identifier</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_set.3.html">nng_dialer_set(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set dialer option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_setopt.3.html">nng_dialer_setopt(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set dialer option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_start.3.html">nng_dialer_start(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">start dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_free.3.html">nng_free(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free memory</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_getopt.3.html">nng_getopt(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get socket option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_inproc_register.3.html">nng_inproc_register(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register inproc transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ipc_register.3.html">nng_ipc_register(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register ipc transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listen.3.html">nng_listen(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create and start listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_close.3.html">nng_listener_close(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_create.3.html">nng_listener_create(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_get.3.html">nng_listener_get(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get listener option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_getopt.3.html">nng_listener_getopt(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get listener option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_id.3.html">nng_listener_id(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return numeric listener identifier</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_set.3.html">nng_listener_set(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set listener option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_setopt.3.html">nng_listener_setopt(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set listener option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_start.3.html">nng_listener_start(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">start listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate a message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_append.3.html">nng_msg_append(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">append to message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_body.3.html">nng_msg_body(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_capacity.3.html">nng_msg_capacity(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return message body length</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_chop.3.html">nng_msg_chop(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">remove data from end of message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_clear.3.html">nng_msg_clear(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">clear message body content</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_dup.3.html">nng_msg_dup(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">duplicate a message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_free.3.html">nng_msg_free(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free a message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_get_pipe.3.html">nng_msg_get_pipe(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get pipe for message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header.3.html">nng_msg_header(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return message header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header_append.3.html">nng_msg_header_append(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">append to message header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header_chop.3.html">nng_msg_header_chop(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">remove data from end of message header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header_clear.3.html">nng_msg_header_clear(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">clear message header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header_insert.3.html">nng_msg_header_insert(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">prepend to message header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header_len.3.html">nng_msg_header_len(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return message header length</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header_trim.3.html">nng_msg_header_trim(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">remove data from start of message header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_insert.3.html">nng_msg_insert(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">prepend to message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_len.3.html">nng_msg_len(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return message body length</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_realloc.3.html">nng_msg_realloc(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reallocate a message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_reserve.3.html">nng_msg_reserve(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reserve storage for a message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_set_pipe.3.html">nng_msg_set_pipe(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set pipe for message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_trim.3.html">nng_msg_trim(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">remove data from start of message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pair_open.3.html">nng_pair_open(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create pair socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_close.3.html">nng_pipe_close(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close pipe</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_dialer.3.html">nng_pipe_dialer(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return dialer that created pipe</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_get.3.html">nng_pipe_get(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get pipe option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_getopt.3.html">nng_pipe_getopt(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get pipe option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_id.3.html">nng_pipe_id(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return numeric pipe identifier</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_listener.3.html">nng_pipe_listener(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return listener that created pipe</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_notify.3.html">nng_pipe_notify(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register pipe notification callback</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_socket.3.html">nng_pipe_socket(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return owning socket for pipe</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pub_open.3.html">nng_pub_open(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create pub socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pull_open.3.html">nng_pull_open(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create pull socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_push_open.3.html">nng_push_open(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create push socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_recv.3.html">nng_recv(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">recv data</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_recv_aio.3.html">nng_recv_aio(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive message asynchronously</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_recvmsg.3.html">nng_recvmsg(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive a message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_rep_open.3.html">nng_rep_open(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create rep socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_req_open.3.html">nng_req_open(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create req socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_respondent_open.3.html">nng_respondent_open(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create respondent socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_send.3.html">nng_send(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send data</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_send_aio.3.html">nng_send_aio(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send message asynchronously</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sendmsg.3.html">nng_sendmsg(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_setopt.3.html">nng_setopt(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set socket option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sleep_aio.3.html">nng_sleep_aio(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">sleep asynchronously</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_socket_get.3.html">nng_socket_get(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get socket option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_socket_id.3.html">nng_socket_id(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return numeric socket identifier</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_socket_set.3.html">nng_socket_set(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set socket option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_bool.3.html">nng_stat_bool(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic Boolean value</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_child.3.html">nng_stat_child(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get child statistic</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_desc.3.html">nng_stat_desc(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic description</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_find.3.html">nng_stat_find(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">find statistic by name</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_find_dialer.3.html">nng_stat_find_dialer(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">find dialer statistics</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_find_listener.3.html">nng_stat_find_listener(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">find listener statistics</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_find_socket.3.html">nng_stat_find_socket(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">find socket statistics</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_name.3.html">nng_stat_name(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic name</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_next.3.html">nng_stat_next(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get next statistic</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_string.3.html">nng_stat_string(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic string value</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_timestamp.3.html">nng_stat_timestamp(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic timestamp</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_type.3.html">nng_stat_type(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic type</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_unit.3.html">nng_stat_unit(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic unit</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_value.3.html">nng_stat_value(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic numeric value</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stats_free.3.html">nng_stats_free(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free statistics snapshot</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stats_get.3.html">nng_stats_get(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistics snapshot</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_strdup.3.html">nng_strdup(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">duplicate string</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_strerror.3.html">nng_strerror(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return an error description</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_strfree.3.html">nng_strfree(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free memory</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sub_open.3.html">nng_sub_open(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create sub socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_surveyor_open.3.html">nng_surveyor_open(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create surveyor socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tcp_register.3.html">nng_tcp_register(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register tcp transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_register.3.html">nng_tls_register(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register tls transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_url_clone.3.html">nng_url_clone(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">clone URL structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_url_free.3.html">nng_url_free(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free a URL structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_url_parse.3.html">nng_url_parse(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create URL structure from a string</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_version.3.html">nng_version(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">report library version</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ws_register.3.html">nng_ws_register(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register WebSocket transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_wss_register.3.html">nng_wss_register(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register WebSocket secure transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_zt_register.3.html">nng_zt_register(3)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register ZeroTier transport</p></td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="sect1"> +<h2 id="_section_3compat_compatible_library_functions">Section 3compat: Compatible Library Functions</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This section documents the <em>nanomsg</em> 1.0 libary compatible functions.</p> +</div> +<div class="paragraph"> +<p>These functions are provided as a transition aid, for application +developers coming to <em>NNG</em> from <em>libnanomsg</em>, and are discouraged +from use in new applications.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +While this is discouraged for long term use, as a transition aid +applications may use the value returned by the +<a href="nng_socket_id.3.html"><code>nng_socket_id()</code></a> in these functions just like a +socket descriptor (as if the socket were opened via +<a href="nn_socket.3compat.html"><code>nn_socket()</code></a>). +This sort of API intermixing should only be used during transition from +the legacy API to the new API. +</td> +</tr> +</table> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 37.5%;"> +<col style="width: 62.5%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_allocmsg.3compat.html">nn_allocmsg(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate message (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_bind.3compat.html">nn_bind(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">accept connections from remote peers (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_close.3compat.html">nn_close(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close socket (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_cmsg.3compat.html">nn_cmsg(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">message control data (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_connect.3compat.html">nn_connect(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">connect to remote peer (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_device.3compat.html">nn_device(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create forwarding device (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_errno.3compat.html">nn_errno(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return most recent error (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_freemsg.3compat.html">nn_freemsg(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free message (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_get_statistic.3compat.html">nn_get_statistic(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic (stub)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_getsockopt.3compat.html">nn_getsockopt(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get socket option (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_poll.3compat.html">nn_poll(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">poll sockets (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_reallocmsg.3compat.html">nn_reallocmsg(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reallocate message (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_recv.3compat.html">nn_recv(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive data (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_recvmsg.3compat.html">nn_recvmsg(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive message (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_send.3compat.html">nn_send(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send data (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_sendmsg.3compat.html">nn_sendmsg(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send message (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_setsockopt.3compat.html">nn_setsockopt(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set socket option (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_shutdown.3compat.html">nn_shutdown(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">shut down endpoint (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_socket.3compat.html">nn_socket(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create socket (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_strerror.3compat.html">nn_strerror(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return message for error (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nn_term.3compat.html">nn_term(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">terminate library (compatible API)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_compat.3compat.html">nng_compat(3compat)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">compatibility with nanomsg 1.0</p></td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="sect1"> +<h2 id="_section_3http_supplemental_http_functions">Section 3http: Supplemental HTTP Functions</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This section documents supplemental HTTP (HyperText Transport Protocol) +support functions that are available.</p> +</div> +<div class="paragraph"> +<p>These functions can be used in conjunction with the +<a href="nng_ws.7.html">WebSocket</a> transport for Scalability Protocols, or they +may be used to construct other types of applications that communicate +using HTTP.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +At present NNG only supports HTTP/1.0 and HTTP/1.1. +</td> +</tr> +</table> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 37.5%;"> +<col style="width: 62.5%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_client_alloc.3http.html">nng_http_client_alloc(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate HTTP client</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">establish HTTP client connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_client_free.3http.html">nng_http_client_free(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free HTTP client</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_client_get_tls.3http.html">nng_http_client_get_tls(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get HTTP client TLS configuration</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_client_set_tls.3http.html">nng_http_client_set_tls(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP client TLS configuration</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_client_transact.3http.html">nng_http_client_transact(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">perform one HTTP transaction</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_close.3http.html">nng_http_conn_close(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close HTTP connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_read.3http.html">nng_http_conn_read(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">read from HTTP connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_read_all.3http.html">nng_http_conn_read_all(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">read all from HTTP connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_read_req.3http.html">nng_http_conn_read_req(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">read HTTP request</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_read_res.3http.html">nng_http_conn_read_res(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">read HTTP response</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_transact.3http.html">nng_http_conn_transact(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">perform one HTTP transaction on connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_write.3http.html">nng_http_conn_write(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">write to HTTP connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_write_all.3http.html">nng_http_conn_write_all(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">write all to HTTP connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_write_req.3http.html">nng_http_conn_write_req(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">write HTTP request</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_write_res.3http.html">nng_http_conn_write_res(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">write HTTP response</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate HTTP server handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_collect_body.3http.html">nng_http_handler_collect_body(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP handler to collect request body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_free.3http.html">nng_http_handler_free(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free HTTP server handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_get_data.3http.html">nng_http_handler_get_data(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return extra data for HTTP handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_set_data.3http.html">nng_http_handler_set_data(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set extra data for HTTP handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_set_host.3http.html">nng_http_handler_set_host(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set host for HTTP handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_set_method.3http.html">nng_http_handler_set_method(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP handler method</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_set_tree.3http.html">nng_http_handler_set_tree(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP handler to match trees</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_hijack.3http.html">nng_http_hijack(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">hijack HTTP server connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_add_header.3http.html">nng_http_req_add_header(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">add HTTP request header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate HTTP request structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_copy_data.3http.html">nng_http_req_copy_data(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">copy HTTP request body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_del_header.3http.html">nng_http_req_del_header(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">delete HTTP request header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_free.3http.html">nng_http_req_free(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free HTTP request structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_get_data.3http.html">nng_http_req_get_data(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get HTTP request body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_get_header.3http.html">nng_http_req_get_header(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP request header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_get_method.3http.html">nng_http_req_get_method(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP request method</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_get_uri.3http.html">nng_http_req_get_uri(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP request URI</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_get_version.3http.html">nng_http_req_get_version(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP request protocol version</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_reset.3http.html">nng_http_req_reset(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reset HTTP request structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_set_data.3http.html">nng_http_req_set_data(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP request body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_set_header.3http.html">nng_http_req_set_header(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP request header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_set_method.3http.html">nng_http_req_set_method(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP request method</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_set_uri.3http.html">nng_http_req_set_uri(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP request URI</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_set_version.3http.html">nng_http_req_set_version(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP request protocol version</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_add_header.3http.html">nng_http_res_add_header(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">add HTTP response header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate HTTP response structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_alloc_error.3http.html">nng_http_res_alloc_error(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate HTTP error response</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_copy_data.3http.html">nng_http_res_copy_data(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">copy HTTP response body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_del_header.3http.html">nng_http_res_del_header(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">delete HTTP response header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_free.3http.html">nng_http_res_free(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free HTTP response structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_get_data.3http.html">nng_http_res_get_data(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get HTTP response body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_get_header.3http.html">nng_http_res_get_header(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP response header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_get_reason.3http.html">nng_http_res_get_reason(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP response reason</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_get_status.3http.html">nng_http_res_get_status(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP status code</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_get_version.3http.html">nng_http_res_get_version(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP response protocol version</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_reset.3http.html">nng_http_res_reset(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reset HTTP response structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_set_data.3http.html">nng_http_res_set_data(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP response body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_set_header.3http.html">nng_http_res_set_header(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP response header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_set_reason.3http.html">nng_http_res_set_reason(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP response reason</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_set_status.3http.html">nng_http_res_set_status(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP response status</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_set_version.3http.html">nng_http_res_set_version(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP response protocol version</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">add HTTP server handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_del_handler.3http.html">nng_http_server_del_handler(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">delete HTTP server handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_get_addr.3http.html">nng_http_server_get_addr(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get HTTP server address</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_get_tls.3http.html">nng_http_server_get_tls(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get HTTP server TLS configuration</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_hold.3http.html">nng_http_server_hold(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get and hold HTTP server instance</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_release.3http.html">nng_http_server_release(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">release HTTP server instance</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_res_error.3http.html">nng_http_server_res_error(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">use HTTP server error page</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_set_error_file.3http.html">nng_http_server_set_error_file(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set custom HTTP error file</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_set_error_page.3http.html">nng_http_server_set_error_page(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set custom HTTP error page</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_set_tls.3http.html">nng_http_server_set_tls(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP server TLS configuration</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_start.3http.html">nng_http_server_start(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">start HTTP server</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_stop.3http.html">nng_http_server_stop(3http)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">stop HTTP server</p></td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="sect1"> +<h2 id="_section_3str_supplemental_tcp_functions">Section 3str: Supplemental TCP Functions</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This section documents supplemental byte stream functions that +are available.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 37.5%;"> +<col style="width: 62.5%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_close.3str.html">nng_stream_close(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer_alloc.3str.html">nng_stream_dialer_alloc(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate byte stream dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer_close.3str.html">nng_stream_dialer_close(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close byte stream dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer_dial.3str.html">nng_stream_dialer_dial(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">initiate outgoing byte stream connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer_free.3str.html">nng_stream_dialer_free(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free byte stream dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer_get.3str.html">nng_stream_dialer_get(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get option from byte stream dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer_set.3str.html">nng_stream_dialer_set(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set option on byte stream dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_free.3str.html">nng_stream_free(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_get.3str.html">nng_stream_get(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get option from byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_accept.3str.html">nng_stream_listener_accept(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">accept incoming byte stream connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_alloc.3str.html">nng_stream_listener_alloc(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate byte stream listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_close.3str.html">nng_stream_listener_close(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close byte stream listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_free.3str.html">nng_stream_listener_free(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free byte stream listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_get.3str.html">nng_stream_listener_get(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get option from byte stream listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_listen.3str.html">nng_stream_listener_listen(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">bind listener to configured address</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_set.3str.html">nng_stream_listener_set(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set option on byte stream listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_recv.3str.html">nng_stream_recv(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive from byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_send.3str.html">nng_stream_send(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send to byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_set.3str.html">nng_stream_set(3str)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set option on byte stream</p></td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="sect1"> +<h2 id="_section_3supp_supplemental_functions">Section 3supp: Supplemental Functions</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This section documents supplemental functions that are available. +These functions are not intrinsic to building Scalability Protocols +applications with this library.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 37.5%;"> +<col style="width: 62.5%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_clock.3supp.html">nng_clock(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get time</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_cv_alloc.3supp.html">nng_cv_alloc(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate condition variable</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_cv_free.3supp.html">nng_cv_free(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free condition variable</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_cv_until.3supp.html">nng_cv_until(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">wait for condition or timeout</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_cv_wait.3supp.html">nng_cv_wait(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">wait for condition</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_cv_wake.3supp.html">nng_cv_wake(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">wake all waiters</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_cv_wake1.3supp.html">nng_cv_wake1(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">wake one waiter</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_id_map.3supp.html">nng_id_map(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">identifier based mapping table</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msleep.3supp.html">nng_msleep(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">sleep milliseconds</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_mtx_alloc.3supp.html">nng_mtx_alloc(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate mutex</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_mtx_free.3supp.html">nng_mtx_free(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free mutex</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_mtx_lock.3supp.html">nng_mtx_lock(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">lock mutex</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_mtx_unlock.3supp.html">nng_mtx_unlock(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">unlock mutex</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_opts_parse.3supp.html">nng_opts_parse(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">parse command line options</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_random.3supp.html">nng_random(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get random number</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_socket_pair.3supp.html">nng_socket_pair(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create a connected pair of BSD sockets</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_thread_create.3supp.html">nng_thread_create(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create thread</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_thread_destroy.3supp.html">nng_thread_destroy(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reap thread</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_thread_set_name.3supp.html">nng_thread_set_name(3supp)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set thread name</p></td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="sect1"> +<h2 id="_section_3tls_supplemental_tls_functions">Section 3tls: Supplemental TLS Functions</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This section documents supplemental TLS (Transport Layer Security) +functions that are available. +TLS support is available when using Scalability Protocols with +the <a href="nng_tls.7.html">TLS</a> transport, or when using WebSocket, either +with the <a href="nng_ws.7.html">WebSocket</a> transport for Scalability Protocols, +or combined with other HTTP capabilities.</p> +</div> +<div class="paragraph"> +<p>These functions depend on library support that is not included directly +with <em>NNG</em> however, so their presence will depend on whether this +additional support was present and enabled with <em>libnng</em> was built.</p> +</div> +<div class="paragraph"> +<p>Currently, this extra support can be provided by the +<a href="https://tls.mbed.org">mbedTLS library</a> or by external plug-ins.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Contact <a href="https://staysail.tech">Staysail Systems, Inc.</a> for +details about commercially available options, including support for +FIPS 140-2 validated cryptography and TLS v1.3. +</td> +</tr> +</table> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 37.5%;"> +<col style="width: 62.5%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate TLS configuration object</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_auth_mode.3tls.html">nng_tls_config_auth_mode(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">configure authentication mode</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_ca_chain.3tls.html">nng_tls_config_ca_chain(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">configure certificate authority certificate chain</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_ca_file.3tls.html">nng_tls_config_ca_file(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">load certificate authority from file</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_cert_key_file.3tls.html">nng_tls_config_cert_key_file(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">load own certificate and key from file</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_free.3tls.html">nng_tls_config_free(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">deallocate a TLS configuration object</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_hold.3tls.html">nng_tls_config_hold(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">hold TLS configuration object</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_own_cert.3tls.html">nng_tls_config_own_cert(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">configure own certificate and key</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_server_name.3tls.html">nng_tls_config_server_name(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">configure remote server name</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_version.3tls.html">nng_tls_config_version(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">configure TLS version</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_engine_description.3tls.html">nng_tls_engine_description(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">TLS engine description</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_engine_fips_mode.3tls.html">nng_tls_engine_fips_mode(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">TLS FIPS 140-2 mode indicator</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_engine_name.3tls.html">nng_tls_engine_name(3tls)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">TLS engine name</p></td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="sect1"> +<h2 id="_section_5_macros_and_types">Section 5: Macros and Types</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This section documents core macros and types that are available.</p> +</div> +<div class="paragraph"> +<p>These are the core types and macros that most Scalabilty Protocols +applications need will use.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 37.5%;"> +<col style="width: 62.5%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio.5.html">nng_aio(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">asynchronous I/O handle</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx.5.html">nng_ctx(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">protocol context</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer.5.html">nng_dialer(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_duration.5.html">nng_duration(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">relative time in milliseconds</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_iov.5.html">nng_iov(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">scatter/gather element</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ipc_options.5.html">nng_ipc_options(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">IPC-specific options</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener.5.html">nng_listener(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg.5.html">nng_msg(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_options.5.html">nng_options(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">socket, dialer, listener, and pipe options</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe.5.html">nng_pipe(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">communications pipe</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sockaddr.5.html">nng_sockaddr(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">socket address</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sockaddr_abstract.5.html">nng_sockaddr_abstract(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">abstract IPC socket address</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sockaddr_in.5.html">nng_sockaddr_in(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">IPv4 socket address</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sockaddr_in6.5.html">nng_sockaddr_in6(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">IPv6 socket address</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sockaddr_inproc.5.html">nng_sockaddr_inproc(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">inproc socket address</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sockaddr_ipc.5.html">nng_sockaddr_ipc(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">IPC socket address</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sockaddr_zt.5.html">nng_sockaddr_zt(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">ZeroTier socket address</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_socket.5.html">nng_socket(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">socket handle</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat.5.html">nng_stat(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">statistic</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream.5.html">nng_stream(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer.5.html">nng_stream_dialer(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">byte stream dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener.5.html">nng_stream_listener(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">byte stream listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tcp_options.5.html">nng_tcp_options(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">TCP-specific options</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config.5.html">nng_tls_config(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">TLS configuration object</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_engine.5.html">nng_tls_engine(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">TLS engine implementation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_options.5.html">nng_tls_options(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">TLS-specific options</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_url.5.html">nng_url(5)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">Universal Resource Locator object</p></td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="sect1"> +<h2 id="_section_7_protocols_and_transports">Section 7: Protocols and Transports</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This sections documents various protocols and transports that are +available in the distribution.</p> +</div> +<div class="paragraph"> +<p> +Protocols implement communication patterns, such as +request/reply, publish/subscribe, and so forth. +A given <a href="nng_socket.5.html">socket</a> is created with exactly one protocol, and that +protocol defines the key behavior of the socket.</p> +</div> +<div class="paragraph"> +<p> +Conversely, transports are the underlying mechansims by which messages +are moved between participants, such as TCP/IP or UNIX domain IPC. +A given <a href="nng_socket.5.html">socket</a> may be using several transports at the same +time.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 37.5%;"> +<col style="width: 62.5%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng.7.html">nng(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">nanomsg next generation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_bus.7.html">nng_bus(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">bus protocol</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_inproc.7.html">nng_inproc(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">intra-process transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ipc.7.html">nng_ipc(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">IPC transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pair.7.html">nng_pair(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">pair protocol</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pub.7.html">nng_pub(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">publisher protocol</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pull.7.html">nng_pull(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">pull protocol</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_push.7.html">nng_push(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">push protocol</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_rep.7.html">nng_rep(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reply protocol</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_req.7.html">nng_req(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">request protocol</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_respondent.7.html">nng_respondent(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">respondent protocol</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_socket.7.html">nng_socket(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">BSD Socket transport (experimental)</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sub.7.html">nng_sub(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">subscriber protocol</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_surveyor.7.html">nng_surveyor(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">surveyor protocol</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tcp.7.html">nng_tcp(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">TCP/IP transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls.7.html">nng_tls(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">TLS transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ws.7.html">nng_ws(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">WebSocket transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_zerotier.7.html">nng_zerotier(7)</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">ZeroTier transport</p></td> +</tr> +</tbody> +</table> +</div> +</div> diff --git a/man/v1.7.2/libnng.3.html b/man/v1.7.2/libnng.3.html new file mode 100644 index 00000000..44e7b11a --- /dev/null +++ b/man/v1.7.2/libnng.3.html @@ -0,0 +1,1406 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: libnng(3) +--- +<h1>libnng(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>libnng - nanomsg next generation library</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p><strong>cc</strong> [<em>flags</em>] <em>files</em> <strong>-lnng</strong> [<em>libraries</em>]</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p><a href="nng.7.html"><em>NNG</em></a> provides a common messaging framework +intended to solve common communication problems in distributed applications.</p> +</div> +<div class="paragraph"> +<p>It provides a C language API.</p> +</div> +<div class="sect2"> +<h3 id="_common_functions">Common Functions</h3> +<div class="paragraph"> +<p>The following common functions exist in <em>libnng</em>.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_alloc.3.html">nng_alloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate memory</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_free.3.html">nng_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free memory</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_strdup.3.html">nng_strdup()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">duplicate string</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_strerror.3.html">nng_strerror()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return an error description</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_strfree.3.html">nng_strfree()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free string</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_version.3.html">nng_version()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">report library version</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_socket_functions">Socket Functions</h3> +<div class="paragraph"> +<p>The following functions operate on sockets.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_close.3.html">nng_close()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dial.3.html">nng_dial()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create and start dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_getopt.3.html">nng_getopt()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get socket option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listen.3.html">nng_listen()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create and start listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_recv.3.html">nng_recv()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive data</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_send.3.html">nng_send()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send data</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_setopt.3.html">nng_setopt()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set socket option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_socket_get.3.html">nng_socket_get()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get socket option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_socket_id.3.html">nng_socket_id()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get numeric socket identifier</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_socket_set.3.html">nng_socket_set()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set socket option</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_connection_management">Connection Management</h3> +<div class="paragraph"> +<p>The following functions are used with either listeners, or dialers. +Listeners accept incoming connection requests, and dialers make them.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dial.3.html">nng_dial()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create and start dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_close.3.html">nng_dialer_close()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_create.3.html">nng_dialer_create()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_get.3.html">nng_dialer_get()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get dialer option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_getopt.3.html">nng_dialer_getopt()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get dialer option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_id.3.html">nng_dialer_id()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get numeric dialer identifier</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_set.3.html">nng_dialer_set()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set dialer option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_setopt.3.html">nng_dialer_setopt()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set dialer option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_dialer_start.3.html">nng_dialer_start()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">start dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listen.3.html">nng_listen()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create and start listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_close.3.html">nng_listener_close()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_create.3.html">nng_listener_create()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_get.3.html">nng_listener_get()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get listener option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_getopt.3.html">nng_listener_getopt()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get listener option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_id.3.html">nng_listener_id()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get numeric listener identifier</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_set.3.html">nng_listener_set()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set listener option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_setopt.3.html">nng_listener_setopt()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set listener option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_listener_start.3.html">nng_listener_start()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">start listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_close.3.html">nng_pipe_close()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close pipe</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_dialer.3.html">nng_pipe_dialer()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return dialer that created pipe</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_get.3.html">nng_pipe_get()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get pipe option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_getopt.3.html">nng_pipe_getopt()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get pipe option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_id.3.html">nng_pipe_id()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get numeric pipe identifier</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_listener.3.html">nng_pipe_listener()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return listener that created pipe</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_notify.3.html">nng_pipe_notify()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register pipe notification callback</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pipe_socket.3.html">nng_pipe_socket()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return owning socket for pipe</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_message_handling_functions">Message Handling Functions</h3> +<div class="paragraph"> +<p>Applications desiring to use the richest part of <em>libnng</em> 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.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_alloc.3.html">nng_msg_alloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate a message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_append.3.html">nng_msg_append()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">append to message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_body.3.html">nng_msg_body()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_capacity.3.html">nng_msg_capacity()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return capacity allocated for message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_chop.3.html">nng_msg_chop()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">remove data from end of message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_clear.3.html">nng_msg_clear()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">clear message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_dup.3.html">nng_msg_dup()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">duplicate a message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_free.3.html">nng_msg_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free a message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_get_pipe.3.html">nng_msg_get_pipe()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get pipe for message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_insert.3.html">nng_msg_insert()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">prepend to message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_len.3.html">nng_msg_len()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return the message body length</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_realloc.3.html">nng_msg_realloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reallocate a message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_reserve.3.html">nng_msg_reserve()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reserve storage for message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_set_pipe.3.html">nng_msg_set_pipe()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set pipe for message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_trim.3.html">nng_msg_trim()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">remove data from start of message body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_recvmsg.3.html">nng_recvmsg()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive a message</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sendmsg.3.html">nng_sendmsg()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send a message</p></td> +</tr> +</tbody> +</table> +<div class="sect3"> +<h4 id="_message_header_handling">Message Header Handling</h4> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +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. +</td> +</tr> +</table> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header.3.html">nng_msg_header()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return message header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header_append.3.html">nng_msg_header_append()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">append to message header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header_chop.3.html">nng_msg_header_chop()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">remove data from end of message header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header_clear.3.html">nng_msg_header_clear()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">clear message header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header_insert.3.html">nng_msg_header_insert()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">prepend to message header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header_len.3.html">nng_msg_header_len()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return the message header length</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msg_header_trim.3.html">nng_msg_header_trim()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">remove data from start of message header</p></td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_asynchronous_operations">Asynchronous Operations</h3> +<div class="paragraph"> +<p>Most applications will interact with <em>NNG</em> synchronously; that is that +functions such as <a href="nng_send.3.html"><code>nng_send()</code></a> will block the calling +thread until the operation has completed.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +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. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>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 +is executed.</p> +</div> +<div class="paragraph"> +<p>A context structure, an <a href="nng_aio.5.html"><code>nng_aio</code></a>, is allocated and +associated with each asynchronous operation. +Only a single asynchronous operation may be associated with an +<code>nng_aio</code> at any time.</p> +</div> +<div class="paragraph"> +<p>The following functions are used in the asynchronous model:</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_abort.3.html">nng_aio_abort()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">abort asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_alloc.3.html">nng_aio_alloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate asynchronous I/O handle</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_begin.3.html">nng_aio_begin()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">begin asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_busy.3.html">nng_aio_busy()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">test if asynchronous I/O is busy</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_cancel.3.html">nng_aio_cancel()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">cancel asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_count.3.html">nng_aio_count()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return number of bytes transferred</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_defer.3.html">nng_aio_defer()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">defer asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_finish.3.html">nng_aio_finish()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">finish asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_free.3.html">nng_aio_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free asynchronous I/O handle</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_get_input.3.html">nng_aio_get_input()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return input parameter</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_get_msg.3.html">nng_aio_get_msg()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get message from an asynchronous receive</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_get_output.3.html">nng_aio_get_output()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return output result</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_free.3.html">nng_aio_reap()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reap asynchronous I/O handle</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_result.3.html">nng_aio_result()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return result of asynchronous operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_set_input.3.html">nng_aio_set_input()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set input parameter</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_set_iov.3.html">nng_aio_set_iov()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set scatter/gather vector</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_set_msg.3.html">nng_aio_set_msg()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set message for an asynchronous send</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_set_output.3.html">nng_aio_set_output()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set output result</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_set_timeout.3.html">nng_aio_set_timeout()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set asynchronous I/O timeout</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_stop.3.html">nng_aio_stop()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">stop asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_aio_wait.3.html">nng_aio_wait()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">wait for asynchronous I/O operation</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_recv_aio.3.html">nng_recv_aio()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive message asynchronously</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_send_aio.3.html">nng_send_aio()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send message asynchronously</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sleep_aio.3.html">nng_sleep_aio()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">sleep asynchronously</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_protocols">Protocols</h3> +<div class="paragraph"> +<p>The following functions are used to construct a socket with a specific protocol:</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_bus_open.3.html">nng_bus_open()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">open a bus socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pair_open.3.html">nng_pair_open()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">open a pair socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pub_open.3.html">nng_pub_open()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">open a pub socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_pull_open.3.html">nng_pull_open()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">open a pull socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_push_open.3.html">nng_push_open()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">open a push socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_rep_open.3.html">nng_rep_open()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">open a rep socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_req_open.3.html">nng_req_open()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">open a req socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_respondent_open.3.html">nng_respondent_open()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">open a respondent socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_sub_open.3.html">nng_sub_open()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">open a sub socket</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_surveyor_open.3.html">nng_surveyor_open()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">open a surveyor socket</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_transports">Transports</h3> +<div class="paragraph"> +<p>The following functions are used to register a transport for use.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_inproc_register.3.html">nng_inproc_register()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register inproc transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ipc_register.3.html">nng_ipc_register()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register IPC transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tcp_register.3.html">nng_tcp_register()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register TCP transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_register.3.html">nng_tls_register()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register TLS transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ws_register.3.html">nng_ws_register()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register WebSocket transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_wss_register.3.html">nng_wss_register()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register WebSocket Secure transport</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_zt_register.3.html">nng_zt_register()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">register ZeroTier transport</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_protocol_contexts">Protocol Contexts</h3> +<div class="paragraph"> +<p>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.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_close.3.html">nng_ctx_close()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close context</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_get.3.html">nng_ctx_get()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get context option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_getopt.3.html">nng_ctx_getopt()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get context option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_id.3.html">nng_ctx_id()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get numeric context identifier</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_open.3.html">nng_ctx_open()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create context</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_recv.3.html">nng_ctx_recv()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive message using context asynchronously</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_recvmsg.3.html">nng_ctx_recvmsg()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive a message using context</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_send.3.html">nng_ctx_send()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send message using context asynchronously</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_sendmsg.3.html">nng_ctx_sendmsg()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send a message using context</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_set.3.html">nng_ctx_set()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set context option</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_ctx_setopt.3.html">nng_ctx_setopt()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set context option</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_devices_relays">Devices, Relays</h3> +<div class="paragraph"> +<p>The following function family is used to create forwarders or relayers +that route messages from one socket to another.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_device.3.html">nng_device()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">message forwarding device</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_statistics">Statistics</h3> +<div class="paragraph"> +<p>The following functions provide access to statistics which can be used +to observe program behaviors and as an aid in troubleshooting.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_bool.3.html">nng_stat_bool()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic Boolean value</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_child.3.html">nng_stat_child()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get child statistic</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_desc.3.html">nng_stat_name()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic description</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_find.3.html">nng_stat_find()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">find statistic by name</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_find_dialer.3.html">nng_stat_find_dialer()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">find dialer statistics</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_find_listener.3.html">nng_stat_find_listener()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">find listener statistics</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_find_socket.3.html">nng_stat_find_socket()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">find socket statistics</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_name.3.html">nng_stat_name()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic name</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_next.3.html">nng_stat_next()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get next statistic</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_string.3.html">nng_stat_string()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic string value</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_timestamp.3.html">nng_stat_timestamp()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic timestamp</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_type.3.html">nng_stat_type()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic type</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_unit.3.html">nng_stat_unit()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic unit</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stat_value.3.html">nng_stat_value()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistic numeric value</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stats_free.3.html">nng_stats_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free statistics</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stats_get.3.html">nng_stats_get()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get statistics</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_url_object">URL Object</h3> +<div class="paragraph"> +<p>Common functionality is supplied for parsing and handling +universal resource locators (URLS).</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_url_clone.3.html">nng_url_clone()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">clone URL structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_url_free.3.html">nng_url_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free URL structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_url_parse.3.html">nng_url_parse()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create URL structure from string</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_supplemental_api">Supplemental API</h3> +<div class="paragraph"> +<p>These supplemental functions are not intrinsic to building +network applications with <em>NNG</em>, but they are made available +as a convenience to aid in creating portable applications.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_clock.3supp.html">nng_clock()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get time</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_cv_alloc.3supp.html">nng_cv_alloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate condition variable</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_cv_free.3supp.html">nng_cv_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free condition variable</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_cv_until.3supp.html">nng_cv_until()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">wait for condition or timeout</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_cv_wait.3supp.html">nng_cv_wait()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">wait for condition</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_cv_wake.3supp.html">nng_cv_wake()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">wake all waiters</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_cv_wake1.3supp.html">nng_cv_wake1()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">wake one waiter</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_id_map.3supp.html">nng_id_map</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">identifier based mapping table</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_msleep.3supp.html">nng_msleep()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">sleep for milliseconds</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_mtx_alloc.3supp.html">nng_mtx_alloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate mutex</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_mtx_free.3supp.html">nng_mtx_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free mutex</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_mtx_lock.3supp.html">nng_mtx_lock()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">lock mutex</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_mtx_unlock.3supp.html">nng_mtx_unlock()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">unlock mutex</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_opts_parse.3supp.html">nng_opts_parse()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">parse command line options</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_random.3supp.html">nng_random()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get random number</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_socket_pair.3supp.html">nng_socket_pair()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create connected pair of BSD sockets</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_thread_create.3supp.html">nng_thread_create()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">create thread</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_thread_destroy.3supp.html">nng_thread_destroy()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reap thread</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_thread_set_name.3supp.html">nng_thread_set_name()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set thread name</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_byte_streams">Byte Streams</h3> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>Byte streams, represented by +<a href="nng_stream.5.html"><code>nng_stream</code></a> objects, correspond to underlying +connections such as TCP connections or named pipes. +They are created by either +<a href="nng_stream_dialer.5.html"><code>nng_stream_dialer</code></a> or +<a href="nng_stream_listener.5.html"><code>nng_stream_listener</code></a> objects.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_close.3str.html">nng_stream_close()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer_alloc.3str.html">nng_stream_dialer_alloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate byte stream dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer_close.3str.html">nng_stream_dialer_close()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close byte stream dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer_dial.3str.html">nng_stream_dialer_dial()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">initiate outgoing byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer_free.3str.html">nng_stream_dialer_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free byte stream dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer_get.3str.html">nng_stream_dialer_get()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get option from byte stream dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_dialer_set.3str.html">nng_stream_dialer_set()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set option on byte stream dialer</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_free.3str.html">nng_stream_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_get.3str.html">nng_stream_get()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get option from byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_accept.3str.html">nng_stream_listener_accept()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">accept incoming byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_alloc.3str.html">nng_stream_listener_alloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate byte stream listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_close.3str.html">nng_stream_listener_close()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close byte stream listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_free.3str.html">nng_stream_listener_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free byte stream listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_get.3str.html">nng_stream_listener_get()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get option from byte stream listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_listen.3str.html">nng_stream_listener_listen()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">bind byte stream listener to address</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_listener_set.3str.html">nng_stream_listener_set()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set option on byte stream listener</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_recv.3str.html">nng_stream_recv()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">receive from byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_send.3str.html">nng_stream_send()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">send to byte stream</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_stream_set.3str.html">nng_stream_set()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set option on byte stream</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect2"> +<h3 id="_http_support">HTTP Support</h3> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="sect3"> +<h4 id="_common_http_functions">Common HTTP Functions</h4> +<div class="paragraph"> +<p>The following functions are used to work with HTTP requests, responses, +and connections.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_close.3http.html">nng_http_conn_close()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">close HTTP connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_read.3http.html">nng_http_conn_read()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">read from HTTP connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_read_all.3http.html">nng_http_conn_read_all()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">read all from HTTP connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_read_req.3http.html">nng_http_conn_read_req()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">read HTTP request</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_read_res.3http.html">nng_http_conn_read_res()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">read HTTP response</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_write.3http.html">nng_http_conn_write()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">write to HTTP connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_write_all.3http.html">nng_http_conn_write_all()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">write all to HTTP connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_write_req.3http.html">nng_http_conn_write_req()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">write HTTP request</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_write_res.3http.html">nng_http_conn_write_res()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">write HTTP response</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_add_header.3http.html">nng_http_req_add_header()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">add HTTP request header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate HTTP request structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_copy_data.3http.html">nng_http_req_copy_data()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">copy HTTP request body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_del_header.3http.html">nng_http_req_del_header()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">delete HTTP request header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_free.3http.html">nng_http_req_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free HTTP request structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_get_data.3http.html">nng_http_req_get_data()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get HTTP request body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_get_header.3http.html">nng_http_req_get_header()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP request header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_get_method.3http.html">nng_http_req_get_method()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP request method</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_get_uri.3http.html">nng_http_req_get_uri()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP request URI</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_get_version.3http.html">nng_http_req_get_version()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP request protocol version</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_reset.3http.html">nng_http_req_reset()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reset HTTP request structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_set_data.3http.html">nng_http_req_set_data()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP request body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_set_header.3http.html">nng_http_req_set_header()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP request header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_set_method.3http.html">nng_http_req_set_method()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP request method</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_set_uri.3http.html">nng_http_req_set_uri()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP request URI</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_req_set_version.3http.html">nng_http_req_set_version()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP request protocol version</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_add_header.3http.html">nng_http_res_add_header()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">add HTTP response header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate HTTP response structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_alloc_error.3http.html">nng_http_res_alloc_error()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate HTTP error response</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_copy_data.3http.html">nng_http_res_copy_data()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">copy HTTP response body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_del_header.3http.html">nng_http_res_del_header()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">delete HTTP response header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_free.3http.html">nng_http_res_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free HTTP response structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_get_data.3http.html">nng_http_res_get_data()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get HTTP response body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_get_header.3http.html">nng_http_res_get_header()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP response header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_get_reason.3http.html">nng_http_res_get_reason()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP response reason</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_get_status.3http.html">nng_http_res_get_status()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP response status</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_get_version.3http.html">nng_http_res_get_version()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return HTTP response protocol version</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_reset.3http.html">nng_http_res_reset()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">reset HTTP response structure</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_set_data.3http.html">nng_http_res_set_data()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP response body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_set_header.3http.html">nng_http_res_set_header()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP response header</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_set_reason.3http.html">nng_http_res_set_reason()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP response reason</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_set_status.3http.html">nng_http_res_set_status()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP response status</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_res_set_version.3http.html">nng_http_res_set_version()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP response protocol version</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect3"> +<h4 id="_http_client_functions">HTTP Client Functions</h4> +<div class="paragraph"> +<p>These functions are intended for use with HTTP client applications.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_client_alloc.3http.html">nng_http_client_alloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate HTTP client</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_client_connect.3http.html">nng_http_client_connect()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">establish HTTP client connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_client_free.3http.html">nng_http_client_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free HTTP client</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_client_get_tls.3http.html">nng_http_client_get_tls()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get HTTP client TLS configuration</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_client_set_tls.3http.html">nng_http_client_set_tls()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP client TLS configuration</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_client_transact.3http.html">nng_http_client_transact()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">perform one HTTP transaction</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_conn_transact.3http.html">nng_http_conn_transact()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">perform one HTTP transaction on connection</p></td> +</tr> +</tbody> +</table> +</div> +<div class="sect3"> +<h4 id="_http_server_functions">HTTP Server Functions</h4> +<div class="paragraph"> +<p>These functions are intended for use with HTTP server applications.</p> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate HTTP server handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_collect_body.3http.html">nng_http_handler_collect_body()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP handler to collect request body</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_free.3http.html">nng_http_handler_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free HTTP server handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_get_data.3http.html">nng_http_handler_get_data()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">return extra data for HTTP handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_set_data.3http.html">nng_http_handler_set_data()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set extra data for HTTP handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_set_host.3http.html">nng_http_handler_set_host()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set host for HTTP handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_set_method.3http.html">nng_http_handler_set_method()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP handler method</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_handler_set_tree.3http.html">nng_http_handler_set_tree()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP handler to match trees</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_hijack.3http.html">nng_http_hijack()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">hijack HTTP server connection</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">add HTTP server handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_del_handler.3http.html">nng_http_server_del_handler()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">delete HTTP server handler</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_get_addr.3http.html">nng_http_server_get_addr()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get HTTP server address</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_get_tls.3http.html">nng_http_server_get_tls()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get HTTP server TLS configuration</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_hold.3http.html">nng_http_server_hold()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">get and hold HTTP server instance</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_release.3http.html">nng_http_server_release()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">release HTTP server instance</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_set_error_file.3http.html">nng_http_server_set_error_file()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set custom HTTP error file</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_set_error_page.3http.html">nng_http_server_set_error_page()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set custom HTTP error page</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_set_tls.3http.html">nng_http_server_set_tls()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set HTTP server TLS configuration</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_res_error.3http.html">nng_http_server_res_error()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">use HTTP server error page</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_start.3http.html">nng_http_server_start()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">start HTTP server</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_http_server_stop.3http.html">nng_http_server_stop()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">stop HTTP server</p></td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_tls_configuration_objects">TLS Configuration Objects</h3> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +These functions will only be present if the library has been built +with TLS support. +</td> +</tr> +</table> +</div> +<table class="tableblock frame-all grid-all stretch"> +<colgroup> +<col style="width: 50%;"> +<col style="width: 50%;"> +</colgroup> +<tbody> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">allocate TLS configuration</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_auth_mode.3tls.html">nng_tls_config_auth_mode()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set authentication mode</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_ca_chain.3tls.html">nng_tls_config_ca_chain()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set certificate authority chain</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_ca_file.3tls.html">nng_tls_config_ca_file()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">load certificate authority from file</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_cert_key_file.3tls.html">nng_tls_config_cert_key_file()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">load own certificate and key from file</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_own_cert.3tls.html">nng_tls_config_own_cert()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set own certificate and key</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_free.3tls.html">nng_tls_config_free()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">free TLS configuration</p></td> +</tr> +<tr> +<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="nng_tls_config_server_name.3tls.html">nng_tls_config_server_name()</a></p></td> +<td class="tableblock halign-left valign-top"><p class="tableblock">set remote server name</p></td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_allocmsg.3compat.html b/man/v1.7.2/nn_allocmsg.3compat.html new file mode 100644 index 00000000..ddf8d958 --- /dev/null +++ b/man/v1.7.2/nn_allocmsg.3compat.html @@ -0,0 +1,120 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_allocmsg(3compat) +--- +<h1>nn_allocmsg(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_allocmsg - allocate message (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nn_allocmsg</span><span class="tok-p">(</span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">type</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_allocmsg()</code> allocates a message structure of size <em>size</em>, and is +primarily used to support zero-copy send operations, making use of the +<code>NNG_MSG</code> special size indicator. +The value returned is a pointer to the start of the message payload buffer.</p> +</div> +<div class="paragraph"> +<p>The value of <em>size</em> must be positive, and small enough to hold reasonable +message data plus book-keeping information.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The value of <em>type</em> <strong>must</strong> be zero. +(This argument was reserved to support different kinds of memory spaces +for RDMA devices, but this was never developed in the legacy API.)</p> +</div> +<div class="paragraph"> +<p>The returned message must be disposed of by either +<a href="nn_freemsg.3compat.html"><code>nn_freemsg()</code></a> or +<a href="nn_send.3compat.html"><code>nn_send()</code></a> when the caller is finished with it.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns a pointer to message buffer space, or <code>NULL</code> +on failure.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>size</em> or <em>type</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ETERM</code> +</td> +<td class="hdlist2"> +<p>The library is shutting down.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_freemsg.3compat.html">nn_freemsg(3compat)</a>, +<a href="nn_reallocmsg.3compat.html">nn_reallocmsg(3compat)</a>, +<a href="nn_send.3compat.html">nn_send(3compat)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_bind.3compat.html b/man/v1.7.2/nn_bind.3compat.html new file mode 100644 index 00000000..339fac54 --- /dev/null +++ b/man/v1.7.2/nn_bind.3compat.html @@ -0,0 +1,145 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_bind(3compat) +--- +<h1>nn_bind(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_bind - accept connections from remote peers (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">nn_bind</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">)</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_bind()</code> function arranges for the socket <em>sock</em> to +accept connections at the address specified by <em>url</em>. +An identifier for this socket’s association with the <em>url</em> is +returned to the caller on success. +This identfier can be used with +<a href="nn_shutdown.3compat.html"><code>nn_shutdown()</code></a> to +remove the association later.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The bind operation is performed asynchronously, and may not have +completed before this function returns control to the caller. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Only transports supported by legacy <em>libnanomsg</em> may be +used with this function. +In particular, only the schemes <code>tcp://</code>, <code>ipc://</code>, <code>inproc://</code>, and <code>ws://</code> are +supported with this function. +(Use the <a href="libnng.3.html">modern API</a> to use other schemes.) +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns a positive identifier on success, and -1 on error.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>EADDRINUSE</code> +</td> +<td class="hdlist2"> +<p>The address specified by <em>url</em> is already in use.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EADDRNOTAVAIL</code> +</td> +<td class="hdlist2"> +<p>The address specified by <em>url</em> is not available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>The socket <em>sock</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>url</em> was supplied.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_connect.3compat.html">nn_connect(3compat)</a>, +<a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_shutdown.3compat.html">nn_shutdown(3compat)</a>, +<a href="nn_socket.3compat.html">nn_socket(3compat)</a>, +<a href="nng_compat.3compat.html">nn_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_close.3compat.html b/man/v1.7.2/nn_close.3compat.html new file mode 100644 index 00000000..6699078d --- /dev/null +++ b/man/v1.7.2/nn_close.3compat.html @@ -0,0 +1,94 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_close(3compat) +--- +<h1>nn_close(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_close - close socket (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nn_close</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_close()</code> function closes the socket <em>sock</em>. +Any operations that are currently in progress will be terminated, and will +fail with error <code>EBADF</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns zero on success, and -1 on failure.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>The socket is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ETERM</code> +</td> +<td class="hdlist2"> +<p>The library is shutting down.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_socket.3compat.html">nn_socket(3compat)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_cmsg.3compat.html b/man/v1.7.2/nn_cmsg.3compat.html new file mode 100644 index 00000000..09fc20ce --- /dev/null +++ b/man/v1.7.2/nn_cmsg.3compat.html @@ -0,0 +1,111 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_cmsg(3compat) +--- +<h1>nn_cmsg(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_cmsg - message control data (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nn_cmsghdr</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">cmsg_len</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">cmsg_level</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">cmsg_type</span><span class="tok-p">;</span> +<span class="tok-p">};</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_cmsghdr</code> structure describes a block of control data that is +associated with a message either sent by <a href="nn_sendmsg.3compat.html"><code>nn_sendmsg()</code></a> +or received by <a href="nn_recvmsg.3compat.html"><code>nn_recvmsg()</code></a>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This structure and supporting macros are provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Each header is followed by <code>cmsg_len</code> bytes of data, plus any padding required +to align the structure.</p> +</div> +<div class="paragraph"> +<p>The only defined ancillary data at this time is the protocol headers used by +the protocols. +This uses <code>cmsg_level</code> set to <code>PROTO_SP</code> and the <code>cmsg_type</code> set to +<code>SP_HDR</code>. +The actual data for this will vary from depending on the protocol used.</p> +</div> +<div class="paragraph"> +<p>Convenience macros are provided to make working with these fields easier.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>struct nn_cmsghdr *NN_CMSG_FIRSTHDR(struct nn_msghdr *<em>hdr</em>)</code></dt> +<dd> +<p>This macro returns the first <code>struct nn_cmsghdr</code> header in <em>hdr</em>.</p> +</dd> +<dt class="hdlist1"><code>struct nn_cmsghdr *NN_CMSG_NXTHDR(struct nn_msghdr *<em>hdr</em>, struct nn_cmsghdr *<em>ch</em>)</code></dt> +<dd> +<p>This macro returns a pointer to the next <code>struct nn_cmsghdr</code> in <em>hdr</em> after <em>ch</em>.</p> +</dd> +<dt class="hdlist1"><code>void *NN_CMSG_DATA(struct nn_cmsghdr *<em>ch</em>)</code></dt> +<dd> +<p>This macro returns a pointer to the header-specific data for <em>ch</em>.</p> +</dd> +<dt class="hdlist1"><code>size_t NN_CMSG_ALIGN(size_t <em>len</em>)</code></dt> +<dd> +<p>This macro returns the length specified by <em>len</em>, plus any padding required to +provide the necessary alignment for another structure.</p> +</dd> +<dt class="hdlist1"><code>size_t NN_CMSG_SPACE(size_t <em>len</em>)</code></dt> +<dd> +<p>This macro returns the amount of space required for a header, with <em>len</em> +bytes of following data, and any necessary padding.</p> +</dd> +<dt class="hdlist1"><code>size_t NN_CMSG_LEN(size_t <em>len</em>)</code></dt> +<dd> +<p>This macro evaluates to the length of the header (including alignment), +and the associated data of length <em>len</em>, but without any trailing padding +to align for another header.</p> +</dd> +</dl> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_recvmsg.3compat.html">nn_recvmsg(3compat)</a>, +<a href="nn_sendmsg.3compat.html">nn_sendmsg(3compat)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_connect.3compat.html b/man/v1.7.2/nn_connect.3compat.html new file mode 100644 index 00000000..7ba156a0 --- /dev/null +++ b/man/v1.7.2/nn_connect.3compat.html @@ -0,0 +1,137 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_connect(3compat) +--- +<h1>nn_connect(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_connect - connect to remote peer (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">nn_connect</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">)</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_connect()</code> function arranges for the socket <em>sock</em> to +initiate connection to a peer at the address specified by <em>url</em>. +An identifier for this socket’s association with the <em>url</em> is +returned to the caller on success. +This identifier can be used with +<a href="nn_shutdown.3compat.html"><code>nn_shutdown()</code></a> to +remove the association later.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The connect operation is performed asynchronously, and may not have +completed before this function returns control to the caller. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Only transports supported by legacy <em>libnanomsg</em> may be +used with this function. +In particular, only the schemes <code>tcp://</code>, <code>ipc://</code>, <code>inproc://</code>, and <code>ws://</code> are +supported with this function. +(Use the <a href="libnng.3.html">modern API</a> to use other schemes.) +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns a positive identifier success, and -1 on error.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>ECONNREFUSED</code> +</td> +<td class="hdlist2"> +<p>The connection attempt was refused.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>The socket <em>sock</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>url</em> was supplied.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_bind.3compat.html">nn_bind(3compat)</a>, +<a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_shutdown.3compat.html">nn_shutdown(3compat)</a>, +<a href="nn_socket.3compat.html">nn_socket(3compat)</a>, +<a href="nng_compat.3compat.html">nn_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_device.3compat.html b/man/v1.7.2/nn_device.3compat.html new file mode 100644 index 00000000..5fda9cef --- /dev/null +++ b/man/v1.7.2/nn_device.3compat.html @@ -0,0 +1,110 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_device(3compat) +--- +<h1>nn_device(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_device - create forwarding device (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nn_device</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock1</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock2</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_device()</code> function is used to create a forwarder, where messages +received on one of the two sockets <em>sock1</em> and <em>sock2</em> are forwarded to +the other.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The two sockets must be compatible, and must be +<a href="nng.7.html#raw_mode">raw mode</a> +sockets. +More detail about devices and how they can be used is available in the +new style <a href="nng_device.3.html">nng_device()</a> documentation.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function blocks forever, and will return -1 only when +one of the sockets is closed or an error occurs.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>One of the two sockets is invalid or not open, or has</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EINVAL</code> +</td> +<td class="hdlist2"> +<p>The sockets are not compatible with each other, or not both raw.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_socket.3compat.html">nn_socket(3compat)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_errno.3compat.html b/man/v1.7.2/nn_errno.3compat.html new file mode 100644 index 00000000..4c32bbc3 --- /dev/null +++ b/man/v1.7.2/nn_errno.3compat.html @@ -0,0 +1,265 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_errno(3compat) +--- +<h1>nn_errno(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_errno - return most recent error (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nn_errno</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_errno()</code> function returns the error number corresponding to the +most recent failed operation by the calling thread.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +The error numbers returned from this function may include +errors caused by system functions, which overlap the usual <code>errno</code> variable, +and this function simply returns the value of <code>errno</code>. +However, the values returned may include numeric values that are not +defined by the system, but are unique to <em>libnanomsg</em>, such as <code>EFSM</code>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>This library implements the following error numbers, in addition to any others +that might be set for <code>errno</code> by the underlying system:</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the value of <code>errno</code>. +If no operation has failed, then this will be zero.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>EINTR</code> +</td> +<td class="hdlist2"> +<p>Operation interrupted.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EINVAL</code> +</td> +<td class="hdlist2"> +<p>Invalid argument.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EBUSY</code> +</td> +<td class="hdlist2"> +<p>Resource is busy.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Operation timed out.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ECONNREFUSED</code> +</td> +<td class="hdlist2"> +<p>Connection refused by peer.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>Invalid or closed socket.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EAGAIN</code> +</td> +<td class="hdlist2"> +<p>Operation would block.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>Protocol or option not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EADDRINUSE</code> +</td> +<td class="hdlist2"> +<p>Requested address is already in use.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EFSM</code> +</td> +<td class="hdlist2"> +<p>Protocol state incorrect.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EPROTO</code> +</td> +<td class="hdlist2"> +<p>Protocol error.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EHOSTUNREACH</code> +</td> +<td class="hdlist2"> +<p>Remote peer is unreachable.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EADDRNOTAVAIL</code> +</td> +<td class="hdlist2"> +<p>Requested address is not available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EACCES</code> +</td> +<td class="hdlist2"> +<p>Permission denied.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EMSGSIZE</code> +</td> +<td class="hdlist2"> +<p>Message is too large.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ECONNABORTED</code> +</td> +<td class="hdlist2"> +<p>Connection attempt aborted.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>Connection reset by peer.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EEXIST</code> +</td> +<td class="hdlist2"> +<p>Resource already exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EMFILE</code> +</td> +<td class="hdlist2"> +<p>Too many open files.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOSPC</code> +</td> +<td class="hdlist2"> +<p>Insufficient persistent storage.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_strerror.3compat.html">nn_strerror(3compat)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_freemsg.3compat.html b/man/v1.7.2/nn_freemsg.3compat.html new file mode 100644 index 00000000..ac6b73aa --- /dev/null +++ b/man/v1.7.2/nn_freemsg.3compat.html @@ -0,0 +1,77 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_freemsg(3compat) +--- +<h1>nn_freemsg(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_freemsg - free message (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nn_freemsg</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_freemsg()</code> deallocates a message previously allocated with +<a href="nn_allocmsg.3compat.html"><code>nn_allocmsg()</code></a> or similar functions.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function always returns 0.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_allocmsg.3compat.html">nn_allocmsg(3compat)</a>, +<a href="nn_freemsg.3compat.html">nn_freemsg(3compat)</a>, +<a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_get_statistic.3compat.html b/man/v1.7.2/nn_get_statistic.3compat.html new file mode 100644 index 00000000..e1c0a857 --- /dev/null +++ b/man/v1.7.2/nn_get_statistic.3compat.html @@ -0,0 +1,74 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_get_statistic(3compat) +--- +<h1>nn_get_statistic(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_get_statistic - get statistic (stub)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-nf">nn_get_statistic</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">stat</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_get_statistic()</code> function exists only as a stub, and always returns +zero.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Zero.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_getsockopt.3compat.html b/man/v1.7.2/nn_getsockopt.3compat.html new file mode 100644 index 00000000..aa96d0d8 --- /dev/null +++ b/man/v1.7.2/nn_getsockopt.3compat.html @@ -0,0 +1,464 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_getsockopt(3compat) +--- +<h1>nn_getsockopt(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_getsockopt - get socket option (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nn_getsockopt</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">level</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">option</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">szp</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_getsockopt()</code> function gets a socket option on socket <em>sock</em>. +The option retrieved is determined by the <em>level</em> and <em>option</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The value pointed to by <em>szp</em> must be initialized to the size of the buffer +pointed to by <em>val</em>. +No more than this many bytes of the option will be copied into the destination +buffer on success. +On success, the value pointed to by <em>szp</em> will be updated with the actual +size of the option.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +To determine the size to receive an option, first call this function +with <em>val</em> set to <code>NULL</code> and the value addressed by <em>szp</em> initialized to zero. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>level</em> determines whether the option is a generic socket option, +or is transport-specific. +The values possible for level are as follows:</p> +</div> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NN_SOL_SOCKET</code> +</td> +<td class="hdlist2"> +<p>Generic socket option</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_IPC</code> +</td> +<td class="hdlist2"> +<p>Transport specific option for IPC.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_TCP</code> +</td> +<td class="hdlist2"> +<p>Transport specific option for TCP.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_WS</code> +</td> +<td class="hdlist2"> +<p>Transport specific option for WebSocket.</p> +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The following generic socket options are possible (all are of type <code>int</code> and +thus size 4, unless otherwise indicated.)</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_SNDBUF</code></dt> +<dd> +<p>Send buffer size in bytes.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +In <em>NNG</em> buffers are sized as a count of messages rather than +bytes; accordingly this value is the queue depth multiplied by 1024 +(representing an estimate that the average message size is 1kB). +Applications that have unusual message sizes may wish to adjust the value +used here accordingly. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_RCVBUF</code></dt> +<dd> +<p>Receive buffer size in bytes.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The same caveats for <code>NN_SNDBUF</code> apply here as well. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_SNDTIMEO</code></dt> +<dd> +<p>Send time-out in milliseconds. +Send operations will fail with <code>ETIMEDOUT</code> if no message can be received +after this many milliseconds have transpired since the operation was started. +A value of -1 means that no timeout is applied.</p> +</dd> +<dt class="hdlist1"><code>NN_RCVTIMEO</code></dt> +<dd> +<p>Receive time-out in milliseconds. +Receive operations will fail with <code>ETIMEDOUT</code> if no message can be received +after this many milliseconds have transpired since the operation was started. +A value of -1 means that no timeout is applied.</p> +</dd> +<dt class="hdlist1"><code>NN_RCVMAXSIZE</code></dt> +<dd> +<p>Maximum receive size in bytes. +The socket will discard messages larger than this on receive. +The default, 1MB, is intended to prevent denial-of-service attacks. +The value -1 removes any limit.</p> +</dd> +<dt class="hdlist1"><code>NN_RECONNECT_IVL</code></dt> +<dd> +<p>Reconnect interval in milliseconds. +After an outgoing connection is closed or fails, the socket will +automatically attempt to reconnect after this many milliseconds. +This is the starting value for the time, and is used in the first +reconnection attempt after a successful connection is made. +The default is 100.</p> +</dd> +<dt class="hdlist1"><code>NN_RECONNECT_IVL_MAX</code></dt> +<dd> +<p>Maximum reconnect interval in milliseconds. +Subsequent reconnection attempts after a failed attempt are made at +exponentially increasing intervals (back-off), but the interval is +capped by this value. +If this value is smaller than <code>NN_RECONNECT_IVL</code>, then no exponential +back-off is performed, and each reconnect interval will be determined +solely by <code>NN_RECONNECT_IVL</code>. +The default is zero.</p> +</dd> +<dt class="hdlist1"><code>NN_LINGER</code></dt> +<dd> +<p>This option is always zero and exists only for compatibility.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This option was unreliable in early releases of <em>libnanomsg</em>, and +is unsupported in <em>NNG</em> and recent <em>libnanomsg</em> releases. +Applications needing assurance of message delivery should either include an +explicit notification (automatic with the <code>NN_REQ</code> protocol) or allow +sufficient time for the socket to drain before closing the socket or exiting. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_SNDPRIO</code></dt> +<dd> +<p>This option is not implemented at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_RCVPRIO</code></dt> +<dd> +<p>This option is not implemented at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_IPV4ONLY</code></dt> +<dd> +<p>This option is not implemented at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_SOCKET_NAME</code></dt> +<dd> +<p>This option is a string, and represents the socket name. +It can be changed to help with identifying different sockets with +their different application-specific purposes.</p> +</dd> +<dt class="hdlist1"><code>NN_MAXTTL</code></dt> +<dd> +<p>Maximum number of times a message may traverse devices or proxies. +This value, if positive, provides some protection against forwarding loops in +<a href="nng_device.3.html">device</a> chains.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Not all protocols offer this protection, so care should still be used +in configuring device forwarding. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_DOMAIN</code></dt> +<dd> +<p>This option of type <code>int</code> represents either the value <code>AF_SP</code> or <code>AF_SP_RAW</code>, +corresponding to the value that the socket was created with.</p> +</dd> +<dt class="hdlist1"><code>NN_PROTOCOL</code></dt> +<dd> +<p>This option option of type <code>int</code> contains the numeric protocol number +that the socket is used with.</p> +</dd> +<dt class="hdlist1"><code>NN_RCVFD</code></dt> +<dd> +<p>This option returns a file descriptor suitable for use in with <code>poll()</code> or +<code>select()</code> (or other system-specific polling functions). +This descriptor will be readable when a message is available for receiving +at the socket. +This option is of type <code>int</code> on all systems except Windows, where it is of +type <code>SOCKET</code>.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The file descriptor should not be read or written by the application, +and is not the same as any underlying descriptor used for network sockets. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_SNDFD</code></dt> +<dd> +<p>This option returns a file descriptor suitable for use in with <code>poll()</code> or +<code>select()</code> (or other system-specific polling functions). +This descriptor will be readable when the socket is able to accept a message +for sending. +This option is of type <code>int</code> on all systems except Windows, where it is of +type <code>SOCKET</code>.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The file descriptor should not be read or written by the application, +and is not the same as any underlying descriptor used for network sockets. +Furthermore, the file descriptor should only be polled for <em>readability</em>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The following option is available for <code>NN_REQ</code> sockets +using the <code>NN_REQ</code> level:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_REQ_RESEND_IVL</code></dt> +<dd> +<p>Request retry interval in milliseconds. +If an <code>NN_REQ</code> socket does not receive a reply to a request within this +period of time, the socket will automatically resend the request. +The default value is 60000 (one minute).</p> +</dd> +</dl> +</div> +<div class="paragraph"> +<p>The following option is available for <code>NN_SURVEYOR</code> sockets +using the <code>NN_SURVEYOR</code> level:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_SURVEYOR_DEADLINE</code></dt> +<dd> +<p>Survey deadline in milliseconds for <code>NN_SURVEYOR</code> sockets. +After sending a survey message, the socket will only accept responses +from respondents for this long. +Any responses arriving after this expires are silently discarded.</p> +</dd> +</dl> +</div> +<div class="paragraph"> +<p>In addition, the following transport specific options are offered:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_IPC_SEC_ATTR</code></dt> +<dd> +<p>This <code>NN_IPC</code> option is not supported at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_IPC_OUTBUFSZ</code></dt> +<dd> +<p>This <code>NN_IPC</code> option is not supported at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_IPC_INBUFSZE</code></dt> +<dd> +<p>This <code>NN_IPC</code> option is not supported at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_TCP_NODELAY</code></dt> +<dd> +<p>This <code>NN_TCP</code> option is not supported at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_WS_MSG_TYPE</code></dt> +<dd> +<p>This <code>NN_WS</code> option is not supported, as <em>NNG</em> only supports binary messages +in this implementation.</p> +</dd> +</dl> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns zero on success, and -1 on failure.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>The socket <em>sock</em> is not an open socket.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOPROTOOPT</code> +</td> +<td class="hdlist2"> +<p>The level and/or option is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EINVAL</code> +</td> +<td class="hdlist2"> +<p>The option, or the value passed, is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ETERM</code> +</td> +<td class="hdlist2"> +<p>The library is shutting down.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EACCES</code> +</td> +<td class="hdlist2"> +<p>The option cannot be changed.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nn_close.3compat.html">nn_close(3compat)</a>, +<a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_getsockopt.3compat.html">nn_getsockopt(3compat)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_poll.3compat.html b/man/v1.7.2/nn_poll.3compat.html new file mode 100644 index 00000000..8c14aee6 --- /dev/null +++ b/man/v1.7.2/nn_poll.3compat.html @@ -0,0 +1,205 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_poll(3compat) +--- +<h1>nn_poll(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_poll - poll sockets (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-cp">#define NN_POLLIN 1</span> +<span class="tok-cp">#define NN_POLLOUT 2</span> + +<span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nn_pollfd</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">fd</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">events</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">revents</span><span class="tok-p">;</span> +<span class="tok-p">};</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nn_poll</span><span class="tok-p">(</span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nn_pollfd</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">pfds</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">npfd</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">timeout</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_poll()</code> function polls a group of sockets for readiness to send or receive.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The array of <em>nfds</em> sockets to poll for are passed into <em>pfds</em>. +Each member of this array is initialized with the <code>fd</code> field set to +the socket, and the <code>events</code> field set to a mask that can contain either or both +of the flags <code>NN_POLLIN</code> and <code>NN_POLLOUT</code>.</p> +</div> +<div class="paragraph"> +<p>The flag <code>NN_POLLIN</code> indicates that a socket is ready for receiving without +blocking (a message is available on the socket), and the flag <code>NN_POLLOUT</code> +indicates that a socket is ready for sending without blocking.</p> +</div> +<div class="paragraph"> +<p>Upon success, the function returns the number of updates the <code>revents</code> +field of each member of the <em>pfds</em> array, setting it to indicate +whether the requested status is true or not.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The <code>revents</code> field will only have a flag set if the corresponding +flag was also set in the <code>events</code> field. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>If the <em>timeout</em> field is positive, then this function will wait for +up the that many milliseconds. +If none of the requested events occurs before that timeout occurs, then +the function will return -1 and set the error to <code>ETIMEDOUT</code>.</p> +</div> +<div class="paragraph"> +<p>If the <em>timeout</em> is zero, then this function will return immediately, +after updating the current status of the sockets.</p> +</div> +<div class="paragraph"> +<p>If the <em>timeout</em> is -1, then the function waits forever, or until one of the +requested events occurs.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This function is only suitable for use with sockets obtained with the +<a href="nn_socket.3compat.html"><code>nn_socket()</code></a> function, and is not compatible +with file descriptors obtained via any other means. +This includes file descriptors obtained using the <code>NN_SNDFD</code> or <code>NN_RCVFD</code> +options with <a href="nn_getsockopt.3compat.html"><code>nn_getsockopt()</code></a> +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is significantly less efficient than other polling +or asynchronous I/O mechanisms, and is provided for API compatibility only. +It’s use is discouraged. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is <strong>not</strong> supported on systems other than POSIX derived +platforms and Windows. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the number of sockets with events on success, or -1 on error.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>One of the sockets is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Operation timed out.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>This function is not supported on this platform.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_recv.3compat.html">nn_recv(3compat)</a>, +<a href="nn_send.3compat.html">nn_send(3compat)</a>, +<a href="nn_socket.3compat.html">nn_socket(3compat)</a>, +<a href="nng_compat.3compat.html">nn_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_reallocmsg.3compat.html b/man/v1.7.2/nn_reallocmsg.3compat.html new file mode 100644 index 00000000..aa4c908e --- /dev/null +++ b/man/v1.7.2/nn_reallocmsg.3compat.html @@ -0,0 +1,111 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_reallocmsg(3compat) +--- +<h1>nn_reallocmsg(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_reallocmsg - reallocate message (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nn_reallocmsg</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">old</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_reallocmsg()</code> reallocates the message <em>old</em>, making it of size <em>size</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>On success, the contents of <em>old</em> are copied into the new message +(truncating if appropriate), then <em>old</em> is deallocated, and a pointer +to the new message payload is returned.</p> +</div> +<div class="paragraph"> +<p>On failure, the <em>old</em> message is unchanged, and the value <code>NULL</code> is returned +to the caller.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns a pointer to message buffer space, or <code>NULL</code> +on failure.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>size</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ETERM</code> +</td> +<td class="hdlist2"> +<p>The library is shutting down.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_allocmsg.3compat.html">nn_allocmsg(3compat)</a>, +<a href="nn_freemsg.3compat.html">nn_freemsg(3compat)</a>, +<a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_recv.3compat.html b/man/v1.7.2/nn_recv.3compat.html new file mode 100644 index 00000000..6454e1f9 --- /dev/null +++ b/man/v1.7.2/nn_recv.3compat.html @@ -0,0 +1,141 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_recv(3compat) +--- +<h1>nn_recv(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_recv - receive data (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">nn_recv</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">data</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">)</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_recv()</code> function receives a message from the socket <em>sock</em>. +The message body must fit within <em>size</em> bytes, and will be stored +at the location specified by <em>data</em>, unless <em>size</em> is the +special value <code>NN_MSG</code>, indicating a zero-copy operation.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>If <em>size</em> has the special value <code>NN_MSG</code>, then a zero-copy operation +is performed. +In this case, instead of copying the message data into the address +specified by <em>data</em>, a new message large enough to hold the message data +will be allocated (as if by the +function <a href="nn_allocmsg.3compat.html"><code>nn_allocmsg()</code></a>), and the message +payload will be stored accordingly. +In this case, the value stored at <em>data</em> will not be message data, +but a pointer to the message itself. +In this case, on success, the caller shall take responsibility for +the final disposition of the message (such as by sending it to +another peer using <a href="nn_send.3compat.html"><code>nn_send()</code></a>) or +<a href="nn_freemsg.3compat.html"><code>nn_freemsg()</code></a>.</p> +</div> +<div class="paragraph"> +<p>The <em>flags</em> field may contain the special flag <code>NN_DONTWAIT</code>. +In this case, if the no message is available for immediate receipt, +the operation shall not block, but instead will fail with the error <code>EAGAIN</code>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the number of bytes sent on success, and -1 on error.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>EAGAIN</code> +</td> +<td class="hdlist2"> +<p>The operation would block.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>The socket <em>sock</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EFSM</code> +</td> +<td class="hdlist2"> +<p>The socket cannot receive in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>This protocol cannot receive.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Operation timed out.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_recvmsg.3compat.html">nn_recvmsg(3compat)</a>, +<a href="nn_send.3compat.html">nn_send(3compat)</a>, +<a href="nn_socket.3compat.html">nn_socket(3compat)</a>, +<a href="nng_compat.3compat.html">nn_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_recvmsg.3compat.html b/man/v1.7.2/nn_recvmsg.3compat.html new file mode 100644 index 00000000..67de4a3e --- /dev/null +++ b/man/v1.7.2/nn_recvmsg.3compat.html @@ -0,0 +1,175 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_recvmsg(3compat) +--- +<h1>nn_recvmsg(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_recvmsg - receive message (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nn_recvmsg</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nn_msghdr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">hdr</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_recvmsg()</code> function receives a message into the header described by +<em>hdr</em> using the socket <em>sock</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>flags</em> field may contain the special flag <code>NN_DONTWAIT</code>. +In this case, if no message is ready for receiving on <em>sock</em>, +the operation shall not block, but instead will fail with the error <code>EAGAIN</code>.</p> +</div> +<div class="paragraph"> +<p>The <em>hdr</em> points to a structure of type <code>struct nn_msghdr</code>, which has the +following definition:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nn_iovec</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-w"> </span><span class="tok-n">iov_base</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">iov_len</span><span class="tok-p">;</span> +<span class="tok-p">};</span> + +<span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nn_msghdr</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nn_iovec</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg_iov</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">msg_iovlen</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-w"> </span><span class="tok-n">msg_control</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">msg_controllen</span><span class="tok-p">;</span> +<span class="tok-p">};</span></code></pre> +</div> +</div> +<div class="paragraph"> +<p>The <code>msg_iov</code> is an array of scatter items, permitting the message +to be spread into different memory blocks. +There are <code>msg_iovlen</code> elements in this array, each of which +has the base address (<code>iov_base</code>) and length (<code>iov_len</code>) indicated.</p> +</div> +<div class="paragraph"> +<p>The last member of this array may have the <code>iov_len</code> field set to <code>NN_MSG</code>, +in which case the function shall allocate a message buffer, and store the +pointer to it at the address indicated by <code>iov_base</code>. +This can help save an extra copy operation. +The buffer should be deallocated by <a href="nn_freemsg.3compat.html"><code>nn_freemsg()</code></a> +or similar when it is no longer needed.</p> +</div> +<div class="paragraph"> +<p>The values of <code>msg_control</code> and <code>msg_controllen</code> describe a buffer +of ancillary data associated with the message. +This is currently only useful to obtain the message headers +used with <a href="nng.7.html#raw_mode">raw mode</a> sockets. +In all other circumstances these fields should be zero. +Details about this structure are covered in +<a href="nn_cmsg.3compat.html"><code>nn_cmsg(3compat)</code></a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the number of bytes received on success, and -1 on error.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>EAGAIN</code> +</td> +<td class="hdlist2"> +<p>The operation would block.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>The socket <em>sock</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EFSM</code> +</td> +<td class="hdlist2"> +<p>The socket cannot receive in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EINVAL</code> +</td> +<td class="hdlist2"> +<p>The <em>hdr</em> is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>This protocol cannot receive.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Operation timed out.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_cmsg.3compat.html">nn_cmsg(3compat)</a>, +<a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_recv.3compat.html">nn_recv(3compat)</a>, +<a href="nn_send.3compat.html">nn_send(3compat)</a>, +<a href="nn_socket.3compat.html">nn_socket(3compat)</a>, +<a href="nng_compat.3compat.html">nn_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_send.3compat.html b/man/v1.7.2/nn_send.3compat.html new file mode 100644 index 00000000..532eea9a --- /dev/null +++ b/man/v1.7.2/nn_send.3compat.html @@ -0,0 +1,150 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_send(3compat) +--- +<h1>nn_send(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_send - send data (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">nn_send</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">data</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">)</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_send()</code> function creates a message containing <em>data</em> (of size <em>size</em>), +and sends using the socket <em>sock</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>If <em>size</em> has the special value <code>NN_MSG</code>, then a zero-copy operation +is performed. +In this case, <em>data</em> points not to the message content itself, but instead +is a pointer to the pointer, an extra level of pointer indirection. +The message must have been previously allocated by +<a href="nn_allocmsg.3compat.html"><code>nn_allocmsg()</code></a> or +<a href="nn_recvmsg.3compat.html"><code>nn_recvmsg()</code></a><code>, using the same `NN_MSG</code> size. +In this case, the ownership of the message shall remain with +the caller, unless the function returns 0, indicating that the +function has taken responsibility for delivering or disposing of the +message.</p> +</div> +<div class="paragraph"> +<p>The <em>flags</em> field may contain the special flag <code>NN_DONTWAIT</code>. +In this case, if the socket is unable to accept more data for sending, +the operation shall not block, but instead will fail with the error <code>EAGAIN</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The send operation is performed asynchronously, and may not have +completed before this function returns control to the caller. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the number of bytes sent on success, and -1 on error.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>EAGAIN</code> +</td> +<td class="hdlist2"> +<p>The operation would block.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>The socket <em>sock</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EFSM</code> +</td> +<td class="hdlist2"> +<p>The socket cannot send in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>This protocol cannot send.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Operation timed out.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_recv.3compat.html">nn_recv(3compat)</a>, +<a href="nn_sendmsg.3compat.html">nn_sendmsg(3compat)</a>, +<a href="nn_socket.3compat.html">nn_socket(3compat)</a>, +<a href="nng_compat.3compat.html">nn_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_sendmsg.3compat.html b/man/v1.7.2/nn_sendmsg.3compat.html new file mode 100644 index 00000000..cd406f4f --- /dev/null +++ b/man/v1.7.2/nn_sendmsg.3compat.html @@ -0,0 +1,193 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_sendmsg(3compat) +--- +<h1>nn_sendmsg(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_sendmsg - send message (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nn_sendmsg</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nn_msghdr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">hdr</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_sendmsg()</code> function sends the message described by <em>hdr</em> using the +socket <em>sock</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>flags</em> field may contain the special flag <code>NN_DONTWAIT</code>. +In this case, if the socket is unable to accept more data for sending, +the operation shall not block, but instead will fail with the error <code>EAGAIN</code>.</p> +</div> +<div class="paragraph"> +<p>The <em>hdr</em> points to a structure of type <code>struct nn_msghdr</code>, which has the +following definition:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nn_iovec</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-w"> </span><span class="tok-n">iov_base</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">iov_len</span><span class="tok-p">;</span> +<span class="tok-p">};</span> + +<span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nn_msghdr</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nn_iovec</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg_iov</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">msg_iovlen</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-w"> </span><span class="tok-n">msg_control</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">msg_controllen</span><span class="tok-p">;</span> +<span class="tok-p">};</span></code></pre> +</div> +</div> +<div class="paragraph"> +<p>The <code>msg_iov</code> is an array of gather items, permitting the message +to be spread into different memory blocks. +There are <code>msg_iovlen</code> elements in this array, each of which +has the base address (<code>iov_base</code>) and length (<code>iov_len</code>) indicated.</p> +</div> +<div class="paragraph"> +<p>For buffers allocated for zero copy +(such as by <a href="nn_allocmsg.3compat.html"><code>nn_allocmsg()</code></a>), the value +of <code>iov_base</code> should be the address of the pointer to the buffer, +rather than the address of the buffer itself. +In this case, the value of <code>iov_len</code> should be <code>NN_MSG</code>, +as the length is inferred from the allocated message. +If the <code>msg_iovlen</code> field is <code>NN_MSG</code>, then this function will free +the associated buffer after it is done with it, if it returns successfully. +(If the function returns with an error, then the caller retains ownership +of the associated buffer and may retry the operation or free the buffer +at its choice.)</p> +</div> +<div class="paragraph"> +<p>The values of <code>msg_control</code> and <code>msg_controllen</code> describe a buffer +of ancillary data to send the message. +This is currently only useful to provide the message headers +used with <a href="nng.7.html#raw_mode">raw mode</a> sockets. +In all other circumstances these fields should be zero. +Details about this structure are covered in +<a href="nn_cmsg.3compat.html"><code>nn_cmsg(3compat)</code></a>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The send operation is performed asynchronously, and may not have +completed before this function returns control to the caller. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the number of bytes sent on success, and -1 on error.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>EAGAIN</code> +</td> +<td class="hdlist2"> +<p>The operation would block.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>The socket <em>sock</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EFSM</code> +</td> +<td class="hdlist2"> +<p>The socket cannot send in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EINVAL</code> +</td> +<td class="hdlist2"> +<p>The <em>hdr</em> is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>This protocol cannot send.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Operation timed out.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_cmsg.3compat.html">nn_cmsg(3compat)</a>, +<a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_recv.3compat.html">nn_recv(3compat)</a>, +<a href="nn_send.3compat.html">nn_send(3compat)</a>, +<a href="nn_socket.3compat.html">nn_socket(3compat)</a>, +<a href="nng_compat.3compat.html">nn_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_setsockopt.3compat.html b/man/v1.7.2/nn_setsockopt.3compat.html new file mode 100644 index 00000000..d7f2d4c1 --- /dev/null +++ b/man/v1.7.2/nn_setsockopt.3compat.html @@ -0,0 +1,420 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_setsockopt(3compat) +--- +<h1>nn_setsockopt(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_setsockopt - set socket option (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nn_setsockopt</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">level</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">option</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">sz</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_setsockopt()</code> function sets a socket option on socket <em>sock</em>, +affecting the behavior of the socket. +The option set is determined by the <em>level</em> and <em>option</em>. +The value of the option is set by <em>val</em>, and <em>sz</em>, which are pointers to +the actual value and the size of the value, respectively.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>level</em> determines whether the option is a generic socket option, +or is transport-specific. +The values possible for level are as follows:</p> +</div> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NN_SOL_SOCKET</code> +</td> +<td class="hdlist2"> +<p>Generic socket option</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_IPC</code> +</td> +<td class="hdlist2"> +<p>Transport specific option for IPC.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_TCP</code> +</td> +<td class="hdlist2"> +<p>Transport specific option for TCP.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_WS</code> +</td> +<td class="hdlist2"> +<p>Transport specific option for WebSocket.</p> +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The following generic socket options are possible (all are of type <code>int</code> and +thus size 4, unless otherwise indicated.)</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_SNDBUF</code></dt> +<dd> +<p>Send buffer size in bytes.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +In <em>NNG</em> buffers are sized as a count of messages rather than +bytes, and so an attempt to estimate a conversion based upon a predetermined +message size of 1kB is made. +The value supplied is rounded up to the nearest value divisible by 1024, and +then divided by 1024 to convert to a message count. +Applications that have unusual message sizes may wish to adjust the value +used here accordingly. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_RCVBUF</code></dt> +<dd> +<p>Receive buffer size in bytes.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The same caveats for <code>NN_SNDBUF</code> apply here as well. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_SNDTIMEO</code></dt> +<dd> +<p>Send time-out in milliseconds. +Send operations will fail with <code>ETIMEDOUT</code> if no message can be received +after this many milliseconds have transpired since the operation was started. +A value of -1 means that no timeout is applied.</p> +</dd> +<dt class="hdlist1"><code>NN_RCVTIMEO</code></dt> +<dd> +<p>Receive time-out in milliseconds. +Receive operations will fail with <code>ETIMEDOUT</code> if no message can be received +after this many milliseconds have transpired since the operation was started. +A value of -1 means that no timeout is applied.</p> +</dd> +<dt class="hdlist1"><code>NN_RCVMAXSIZE</code></dt> +<dd> +<p>Maximum receive size in bytes. +The socket will discard messages larger than this on receive. +The default, 1MB, is intended to prevent denial-of-service attacks. +The value -1 removes any limit.</p> +</dd> +<dt class="hdlist1"><code>NN_RECONNECT_IVL</code></dt> +<dd> +<p>Reconnect interval in milliseconds. +After an outgoing connection is closed or fails, the socket will +automatically attempt to reconnect after this many milliseconds. +This is the starting value for the time, and is used in the first +reconnection attempt after a successful connection is made. +The default is 100.</p> +</dd> +<dt class="hdlist1"><code>NN_RECONNECT_IVL_MAX</code></dt> +<dd> +<p>Maximum reconnect interval in milliseconds. +Subsequent reconnection attempts after a failed attempt are made at +exponentially increasing intervals (back-off), but the interval is +capped by this value. +If this value is smaller than <code>NN_RECONNECT_IVL</code>, then no exponential +back-off is performed, and each reconnect interval will be determined +solely by <code>NN_RECONNECT_IVL</code>. +The default is zero.</p> +</dd> +<dt class="hdlist1"><code>NN_LINGER</code></dt> +<dd> +<p>This option is ignored, and exists only for compatibility.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This option was unreliable in early releases of <em>libnanomsg</em>, and +is unsupported in <em>NNG</em> and recent <em>libnanomsg</em> releases. +Applications needing assurance of message delivery should either include an +explicit notification (automatic with the <code>NN_REQ</code> protocol) or allow +sufficient time for the socket to drain before closing the socket or exiting. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_SNDPRIO</code></dt> +<dd> +<p>This option is not implemented at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_RCVPRIO</code></dt> +<dd> +<p>This option is not implemented at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_IPV4ONLY</code></dt> +<dd> +<p>This option is not implemented at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_SOCKET_NAME</code></dt> +<dd> +<p>This option is a string, and represents the socket name. +It can be changed to help with identifying different sockets with +their different application-specific purposes.</p> +</dd> +<dt class="hdlist1"><code>NN_MAXTTL</code></dt> +<dd> +<p>Maximum number of times a message may traverse devices or proxies. +This value, if positive, provides some protection against forwarding loops in +<a href="nng_device.3.html">device</a> chains.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Not all protocols offer this protection, so care should still be used +in configuring device forwarding. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The following option is available for <code>NN_REQ</code> sockets +using the <code>NN_REQ</code> level:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_REQ_RESEND_IVL</code></dt> +<dd> +<p>Request retry interval in milliseconds. +If an <code>NN_REQ</code> socket does not receive a reply to a request within this +period of time, the socket will automatically resend the request. +The default value is 60000 (one minute).</p> +</dd> +</dl> +</div> +<div class="paragraph"> +<p>The following options are available for <code>NN_SUB</code> sockets using the <code>NN_SUB</code> level:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_SUB_SUBSCRIBE</code></dt> +<dd> +<p>Subscription topic, for <code>NN_SUB</code> sockets. +This sets a subscription topic. +When a message from a publisher arrives, it is compared against all +subscriptions. +If the first <em>sz</em> bytes of the message are not identical to <em>val</em>, +then the message is silently discarded.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +To receive all messages, subscribe to an empty topic (<em>sz</em> equal to zero). +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_SUB_UNSUBSCRIBE</code></dt> +<dd> +<p>Removes a subscription topic that was earlier established.</p> +</dd> +</dl> +</div> +<div class="paragraph"> +<p>The following option is available for <code>NN_SURVEYOR</code> sockets +using the <code>NN_SURVEYOR</code> level:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_SURVEYOR_DEADLINE</code></dt> +<dd> +<p>Survey deadline in milliseconds for <code>NN_SURVEYOR</code> sockets. +After sending a survey message, the socket will only accept responses +from respondents for this long. +Any responses arriving after this expires are silently discarded.</p> +</dd> +</dl> +</div> +<div class="paragraph"> +<p>In addition, the following transport specific options are offered:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NN_IPC_SEC_ATTR</code></dt> +<dd> +<p>This <code>NN_IPC</code> option is not supported at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_IPC_OUTBUFSZ</code></dt> +<dd> +<p>This <code>NN_IPC</code> option is not supported at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_IPC_INBUFSZE</code></dt> +<dd> +<p>This <code>NN_IPC</code> option is not supported at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_TCP_NODELAY</code></dt> +<dd> +<p>This <code>NN_TCP</code> option is not supported at this time.</p> +</dd> +<dt class="hdlist1"><code>NN_WS_MSG_TYPE</code></dt> +<dd> +<p>This <code>NN_WS</code> option is not supported at this time.</p> +</dd> +</dl> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns zero on success, and -1 on failure.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>The socket <em>sock</em> is not an open socket.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOPROTOOPT</code> +</td> +<td class="hdlist2"> +<p>The level and/or option is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EINVAL</code> +</td> +<td class="hdlist2"> +<p>The option, or the value passed, is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ETERM</code> +</td> +<td class="hdlist2"> +<p>The library is shutting down.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EACCES</code> +</td> +<td class="hdlist2"> +<p>The option cannot be changed.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nn_close.3compat.html">nn_close(3compat)</a>, +<a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_getsockopt.3compat.html">nn_getsockopt(3compat)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_shutdown.3compat.html b/man/v1.7.2/nn_shutdown.3compat.html new file mode 100644 index 00000000..1a6bf031 --- /dev/null +++ b/man/v1.7.2/nn_shutdown.3compat.html @@ -0,0 +1,98 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_shutdown(3compat) +--- +<h1>nn_shutdown(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_shutdown - shut down endpoint (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">nn_shutdown</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">sock</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">ep</span><span class="tok-p">)</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_shutdown()</code> shuts down the endpoint <em>ep</em>, which is either a listener or +a dialer) on the socket <em>sock</em>. +This will stop the socket from either accepting new connections, or establishing +old ones. +Additionally, any established connections associated with <em>ep</em> will be closed.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns zero on success, and -1 on error.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>EBADF</code> +</td> +<td class="hdlist2"> +<p>The socket <em>sock</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>ep</em> was supplied.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_bind.3compat.html">nn_bind(3compat)</a>, +<a href="nn_connect.3compat.html">nn_connect(3compat)</a>, +<a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_socket.3compat.html">nn_socket(3compat)</a>, +<a href="nng_compat.3compat.html">nn_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_socket.3compat.html b/man/v1.7.2/nn_socket.3compat.html new file mode 100644 index 00000000..5eed3008 --- /dev/null +++ b/man/v1.7.2/nn_socket.3compat.html @@ -0,0 +1,238 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_socket(3compat) +--- +<h1>nn_socket(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_socket - create socket (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nn_socket</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">af</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">proto</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_socket()</code> function creates socket using the address family <em>af</em> and +protocol <em>proto</em> and returns it.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Mixing the compatibility API and the modern API is not supported +on a given socket. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Some protocols, transports, and features are only available in the modern API. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The address family <em>af</em> can be one of two values:</p> +</div> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>AF_SP</code> +</td> +<td class="hdlist2"> +<p>Normal socket.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>AF_SP_RAW</code> +</td> +<td class="hdlist2"> +<p><a href="nng.7.html#raw_mode">Raw mode</a> socket.</p> +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The protocol indicates the protocol to be used when creating the socket. +The following protocols are defined:</p> +</div> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NN_PAIR</code> +</td> +<td class="hdlist2"> +<p><a href="nng_pair.7.html">Pair</a> protocol.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_PUB</code> +</td> +<td class="hdlist2"> +<p><a href="nng_pub.7.html">Publisher</a> protocol.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_SUB</code> +</td> +<td class="hdlist2"> +<p><a href="nng_sub.7.html">Subscriber</a> protocol.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_REQ</code> +</td> +<td class="hdlist2"> +<p><a href="nng_req.7.html">Requestor</a> protocol.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_REP</code> +</td> +<td class="hdlist2"> +<p><a href="nng_rep.7.html">Replier</a> protocol.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_PUSH</code> +</td> +<td class="hdlist2"> +<p><a href="nng_push.7.html">Push</a> protocol.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_PULL</code> +</td> +<td class="hdlist2"> +<p><a href="nng_pull.7.html">Pull</a> protocol.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_SURVEYOR</code> +</td> +<td class="hdlist2"> +<p><a href="nng_surveyor.7.html">Surveyor</a> protocol.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_RESPONDENT</code> +</td> +<td class="hdlist2"> +<p><a href="nng_respondent.7.html">Respondent</a> protocol.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NN_BUS</code> +</td> +<td class="hdlist2"> +<p><a href="nng_bus.7.html">Bus</a> protocol.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns a valid socket number on success, and -1 on failure.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>ETERM</code> +</td> +<td class="hdlist2"> +<p>The library is shutting down.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nn_close.3compat.html">nn_close(3compat)</a>, +<a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_strerror.3compat.html b/man/v1.7.2/nn_strerror.3compat.html new file mode 100644 index 00000000..d61049b9 --- /dev/null +++ b/man/v1.7.2/nn_strerror.3compat.html @@ -0,0 +1,75 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_strerror(3compat) +--- +<h1>nn_strerror(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_strerror - return message for error (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nn_strerror</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">err</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_strerror()</code> function returns a human readable message corresponding +to the given error number <em>err</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the message corresponding to <em>err</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nn_term.3compat.html b/man/v1.7.2/nn_term.3compat.html new file mode 100644 index 00000000..6d716cca --- /dev/null +++ b/man/v1.7.2/nn_term.3compat.html @@ -0,0 +1,97 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nn_term(3compat) +--- +<h1>nn_term(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nn_term - terminate library (compatible API)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nn_term</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nn_term()</code> function closes any open sockets, and frees all resources +allocated by the library. +Any operations that are currently in progress will be terminated, and will +fail with error <code>EBADF</code> or <code>ETERM</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is provided for API +<a href="nng_compat.3compat.html">compatibility</a> with legacy <em>libnanomsg</em>. +Consider using the relevant <a href="libnng.3.html">modern API</a> instead. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This function is not thread-safe, and is not suitable for use +in library calls. +The intended purpose of this is to clean up at application termination; for +example by registering this function with <code>atexit()</code>. +This can help prevent false leak reports caused when memory checkers notice +global resources allocated by the library. +Libraries should never use this function, but should explicitly close their +own sockets directly. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nn_errno.3compat.html">nn_errno(3compat)</a>, +<a href="nn_socket.3compat.html">nn_socket(3compat)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng.7.html b/man/v1.7.2/nng.7.html new file mode 100644 index 00000000..0b100737 --- /dev/null +++ b/man/v1.7.2/nng.7.html @@ -0,0 +1,391 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng(7) +--- +<h1>nng(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng - nanomsg next generation</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p><strong>cc</strong> ['flags'] 'files' <strong>-lnng</strong> ['libraries']</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p><em>NNG</em> provides a common messaging framework intended to +solve common communication problems in distributed applications. +It offers a number of <em>protocols</em>, and also a number of <em>transports</em>.</p> +</div> +<div class="paragraph"> +<p>The <em>protocols</em> implement the semantics associated with particular +communications scenarios, such as RPC style services, service discovery, +publish/subscribe, and so forth.</p> +</div> +<div class="paragraph"> +<p>The <em>transports</em> provide support for underlying transport methods, such +as TCP, IPC, websockets, and so forth.</p> +</div> +<div class="paragraph"> +<p><em>NNG</em> is designed to permit easy creation of new <em>transports</em> and, +to a lesser extent, new <em>protocols</em>.</p> +</div> +<div class="paragraph"> +<p><em>NNG</em> is wire compatible with the SP protocols described in +the nanomsg project; projects using +<a href="https://github.com/nanomsg/nanomsg"><em>libnanomsg</em></a> can inter-operate with +nng as well as other conforming implementations. (One such implementation +is <a href="https://github.com/go-mangos/mangos"><em>mangos</em></a>.) +Applications using <em>NNG</em> +which wish to communicate with other libraries must ensure that they only +use protocols or transports offered by the other library.</p> +</div> +<div class="paragraph"> +<p><em>NNG</em> also offers a compatible API, permitting legacy code to +be recompiled or relinked against <em>NNG</em>. When doing this, support for +certain enhancements or features will likely be absent, requiring the +application developer to use the new-style API.</p> +</div> +<div class="paragraph"> +<p><em>NNG</em> is implemented in pure C; if you need bindings for +other languages please check the <a href="http://nanomsg.org/">website</a>.</p> +</div> +<div class="sect2"> +<h3 id="_protocols">Protocols</h3> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<a href="nng_bus.7.html">nng_bus(7)</a> +</td> +<td class="hdlist2"> +<p>Bus protocol</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_pair.7.html">nng_pair(7)</a> +</td> +<td class="hdlist2"> +<p>Pair protocol</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_pub.7.html">nng_pub(7)</a> +</td> +<td class="hdlist2"> +<p>Publisher side of publish/subscribe protocol</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_pull.7.html">nng_pull(7)</a> +</td> +<td class="hdlist2"> +<p>Pull side of pipeline protocol</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_push.7.html">nng_push(7)</a> +</td> +<td class="hdlist2"> +<p>Push side of pipeline protocol</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_sub.7.html">nng_sub(7)</a> +</td> +<td class="hdlist2"> +<p>Subscriber side of publish/subscribe protocol</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_rep.7.html">nng_rep(7)</a> +</td> +<td class="hdlist2"> +<p>Reply side of request/reply protocol</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_req.7.html">nng_req(7)</a> +</td> +<td class="hdlist2"> +<p>Request side of request/reply protocol</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_respondent.7.html">nng_respondent(7)</a> +</td> +<td class="hdlist2"> +<p>Respondent side of survey protocol</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_surveyor.7.html">nng_surveyor(7)</a> +</td> +<td class="hdlist2"> +<p>Surveyor side of survey protocol</p> +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_transports">Transports</h3> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<a href="nng_inproc.7.html">nng_inproc(7)</a> +</td> +<td class="hdlist2"> +<p>Intra-process transport</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_ipc.7.html">nng_ipc(7)</a> +</td> +<td class="hdlist2"> +<p>Inter-process transport</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_socket.7.html">nng_socket(7)</a> +</td> +<td class="hdlist2"> +<p>BSD socket transport</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_tls.7.html">nng_tls(7)</a> +</td> +<td class="hdlist2"> +<p>TLSv1.2 over TCP transport</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_tcp.7.html">nng_tcp(7)</a> +</td> +<td class="hdlist2"> +<p>TCP (and TCPv6) transport</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_ws.7.html">nng_ws(7)</a> +</td> +<td class="hdlist2"> +<p>WebSocket transport</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nng_zerotier.7.html">nng_zerotier(7)</a> +</td> +<td class="hdlist2"> +<p>ZeroTier transport</p> +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_conceptual_overview">Conceptual Overview</h3> +<div class="paragraph"> +<p><em>NNG</em> presents a <em>socket</em> view of networking. +The sockets are constructed using protocol-specific functions, as a given +socket implements precisely one protocol.</p> +</div> +<div class="paragraph"> +<p>Each socket can be used to send and receive messages (if the protocol) +supports it, and implements the appropriate protocol semantics. +For example, <a href="nng_sub.7.html"><em>sub</em></a> sockets automatically filter incoming +messages to discard those for topics that have not been subscribed.</p> +</div> +<div class="paragraph"> +<p><em>NNG</em> sockets are message oriented, so that messages are either delivered +wholly, or not at all. Partial delivery is not possible. +Furthermore, <em>NNG</em> does not provide any other delivery or ordering guarantees; +messages may be dropped or reordered +(Some protocols, such as <a href="nng_req.7.html"><em>req</em></a> may offer stronger +guarantees by performing their own retry and validation schemes.)</p> +</div> +<div class="paragraph"> +<p>Each socket can have zero, one, or many endpoints, which are either +<em>listeners</em> or <em>dialers</em>. +(A given socket may freely choose whether it uses listeners, dialers, or both.) +These endpoints provide access to underlying transports, such as TCP, etc.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>Endpoints do not themselves transport data. +They are instead responsible for the creation of <em>pipes</em>, 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.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="sect3"> +<h4 id="raw_mode">Raw Mode</h4> +<div class="paragraph"> +<p> +Most applications will use sockets in normal, or <em>cooked</em>, mode. +This mode provides the full semantics of the protocol. +For example, <a href="nng_req.7.html"><em>req</em></a> sockets will automatically +match a reply to a request, and resend requests periodically if no reply +was received.</p> +</div> +<div class="paragraph"> +<p>There are situations, such as with <a href="nng_device.3.html">proxies</a>, +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 <em>raw</em> mode sockets.</p> +</div> +<div class="paragraph"> +<p>Raw mode sockets are generally constructed with a different function, +such as <a href="nng_req_open.3.html"><code>nng_req0_open_raw()</code></a>. +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.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The <a href="nng_device.3.html"><code>nng_device()</code></a> function only works with raw mode +sockets, but as it only forwards the messages, no additional application +processing is needed. +</td> +</tr> +</table> +</div> +</div> +<div class="sect3"> +<h4 id="_urls">URLs</h4> +<div class="paragraph"> +<p> +<em>NNG</em> uses universal resource locators (URLs) +following the format specified in +<a href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>, +including some schemes that are unique +to SP. + +The URLs used in <em>NNG</em> are canonicalized as follows, mostly in +accordance with +<a href="https://tools.ietf.org/html/rfc3986#section-6.2.2">RFC 3986 6.2.2</a>:</p> +</div> +<div class="olist arabic"> +<ol class="arabic"> +<li> +<p>The URL is parsed into scheme, userinfo, host, port, path, query and +fragment components. (Not all of these members are necessarily present.)</p> +</li> +<li> +<p>The scheme, hostname, and port if present, are converted to lower case.</p> +</li> +<li> +<p>Percent-encoded values for +<a href="https://tools.ietf.org/html/rfc3986#section-2.3">unreserved characters</a> +converted to their unencoded forms.</p> +</li> +<li> +<p>Additionally URL percent-encoded values for characters in the path +and with numeric values larger than 127 (i.e. not ASCII) are decoded.</p> +</li> +<li> +<p>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.</p> +</li> +<li> +<p>Path segments consisting of <code>.</code> and <code>..</code> are resolved as per +<a href="https://tools.ietf.org/html/rfc3986#section-6.2.2.3">RFC 3986 6.2.2.3</a>.</p> +</li> +<li> +<p>Further, empty path segments are removed, meaning that duplicate +slash (<code>/</code>) separators are removed from the path.</p> +</li> +</ol> +</div> +<div class="paragraph"> +<p>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.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +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. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect2"> +<h3 id="_api">API</h3> +<div class="paragraph"> +<p>The library API is documented at <a href="libnng.3.html">libnng(3)</a>.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_compat.3compat.html">nng_compat(3compat)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio.5.html b/man/v1.7.2/nng_aio.5.html new file mode 100644 index 00000000..4ea28c92 --- /dev/null +++ b/man/v1.7.2/nng_aio.5.html @@ -0,0 +1,84 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio(5) +--- +<h1>nng_aio(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio - asynchronous I/O handle</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_aio</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>An <code>nng_aio</code> is an opaque structure used in conjunction with +asynchronous I/O operations. +Every asynchronous operation uses one of these structures, each of which +can only be used with a single operation at a time.</p> +</div> +<div class="paragraph"> +<p>Asynchronous operations are performed without blocking calling application +threads. +Instead the application registers a callback function to be executed +when the operation is complete (whether successfully or not). +This callback will be executed exactly once.</p> +</div> +<div class="paragraph"> +<p>The asynchronous I/O framework also supports cancellation of +operations that are already in progress +(see <a href="nng_aio_cancel.3.html"><code>nng_aio_cancel()</code></a>), as well setting a maximum +timeout for them to complete within +(see <a href="nng_aio_set_timeout.3.html"><code>nng_aio_set_timeout()</code></a>).</p> +</div> +<div class="paragraph"> +<p>It is also possible to initiate an asynchronous operation, and wait for it to +complete using <a href="nng_aio_wait.3.html"><code>nng_aio_wait()</code></a>.</p> +</div> +<div class="paragraph"> +<p>These structures are created using the <a href="nng_aio_alloc.3.html"><code>nng_aio_alloc()</code></a>, +and destroyed using <a href="nng_aio_free.3.html"><code>nng_aio_free()</code></a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_abort.3.html">nng_aio_abort(3)</a>, +<a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_cancel.3.html">nng_aio_cancel(3)</a>, +<a href="nng_aio_count.3.html">nng_aio_count(3)</a>, +<a href="nng_aio_free.3.html">nng_aio_free(3)</a>, +<a href="nng_aio_get_input.3.html">nng_aio_get_input(3)</a>, +<a href="nng_aio_get_msg.3.html">nng_aio_get_msg(3)</a>, +<a href="nng_aio_get_output.3.html">nng_aio_get_output(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio_set_input.3.html">nng_aio_set_input(3)</a>, +<a href="nng_aio_set_iov.3.html">nng_aio_set_iov(3)</a>, +<a href="nng_aio_set_msg.3.html">nng_aio_set_msg(3)</a>, +<a href="nng_aio_set_timeout.3.html">nng_aio_set_timeout(3)</a>, +<a href="nng_aio_stop.3.html">nng_aio_stop(3)</a>, +<a href="nng_aio_wait.3.html">nng_aio_wait(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_abort.3.html b/man/v1.7.2/nng_aio_abort.3.html new file mode 100644 index 00000000..62e09039 --- /dev/null +++ b/man/v1.7.2/nng_aio_abort.3.html @@ -0,0 +1,75 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_abort(3) +--- +<h1>nng_aio_abort(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_abort - abort asynchronous I/O operation</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_abort</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">err</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_abort()</code> function aborts an operation previously started +with the handle <em>aio</em>. +If the operation is aborted, then the callback +for the handle will be called, and the function +<a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a> will return the error <em>err</em>.</p> +</div> +<div class="paragraph"> +<p>This function does not wait for the operation to be fully aborted, but +returns immediately.</p> +</div> +<div class="paragraph"> +<p>If no operation is currently in progress (either because it has already +finished, or no operation has been started yet), then this function +has no effect.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_cancel.3.html">nng_aio_cancel(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_alloc.3.html b/man/v1.7.2/nng_aio_alloc.3.html new file mode 100644 index 00000000..b07b879d --- /dev/null +++ b/man/v1.7.2/nng_aio_alloc.3.html @@ -0,0 +1,136 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_alloc(3) +--- +<h1>nng_aio_alloc(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_alloc - allocate asynchronous I/O handle</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">aiop</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-o">*</span><span class="tok-n">callb</span><span class="tok-p">)(</span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-p">),</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">arg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_alloc()</code> function allocates a handle for asynchronous I/O +operations, and stores a pointer to it in <em>aiop</em>. +The handle is initialized with a completion callback of <em>callb</em>, +which will be executed when an associated asynchronous operation finishes. +It will be called with the argument <em>arg</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The callback <em>callb</em> must not perform any blocking operations, and +must complete its execution quickly. If <em>callb</em> does block, this can +lead ultimately to an apparent "hang" or deadlock in the application. +This also means you should avoid operations such as allocating new objects, +which also means opening or closing sockets, dialers, and so forth. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +If more complex or blocking work needs to be performed by <em>callb</em>, a separate +thread can be used, along with a <a href="nng_cv_alloc.3supp.html">condition variable</a> +which can be signaled by the callback. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Asynchronous I/O operations all take an <a href="nng_aio.5.html"><code>nng_aio</code></a> +handle such as allocated by this function. +Such operations are usually started by a function that returns immediately. +The operation is then run asynchronously, and completes sometime later. +When that operation is complete, the callback supplied here is called, +and that callback is able to determine the result of the operation using +<a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>, +<a href="nng_aio_count.3.html"><code>nng_aio_count()</code></a>, +and <a href="nng_aio_get_output.3.html"><code>nng_aio_get_output()</code></a>.</p> +</div> +<div class="paragraph"> +<p>It is possible to wait synchronously for an otherwise asynchronous operation +by using the function <a href="nng_aio_wait.3.html"><code>nng_aio_wait()</code></a>. +In that case, it is permissible for <em>callb</em> and <em>arg</em> to both be <code>NULL</code>. +Note that if these are <code>NULL</code>, then it will not be possible to determine when the +operation is complete except by calling the aforementioned +<a href="nng_aio_wait.3.html"><code>nng_aio_wait()</code></a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_abort.3.html">nng_aio_abort(3)</a>, +<a href="nng_aio_cancel.3.html">nng_aio_cancel(3)</a>, +<a href="nng_aio_count.3.html">nng_aio_count(3)</a>, +<a href="nng_aio_free.3.html">nng_aio_free(3)</a>, +<a href="nng_aio_get_input.3.html">nng_aio_get_input(3)</a>, +<a href="nng_aio_get_msg.3.html">nng_aio_get_msg(3)</a>, +<a href="nng_aio_get_output.3.html">nng_aio_get_output(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio_set_input.3.html">nng_aio_set_input(3)</a>, +<a href="nng_aio_set_iov.3.html">nng_aio_set_iov(3)</a>, +<a href="nng_aio_set_msg.3.html">nng_aio_set_msg(3)</a>, +<a href="nng_aio_set_timeout.3.html">nng_aio_set_timeout(3)</a>, +<a href="nng_aio_stop.3.html">nng_aio_stop(3)</a>, +<a href="nng_aio_wait.3.html">nng_aio_wait(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_begin.3.html b/man/v1.7.2/nng_aio_begin.3.html new file mode 100644 index 00000000..4c2f3a3e --- /dev/null +++ b/man/v1.7.2/nng_aio_begin.3.html @@ -0,0 +1,110 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_begin(3) +--- +<h1>nng_aio_begin(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_begin - begin asynchronous I/O operation</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_begin</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_begin()</code> function is called by the I/O provider to indicate that +it is going to process the operation.</p> +</div> +<div class="paragraph"> +<p>The function may return <code>false</code>, indicating that the <em>aio</em> has been closed +by the caller asynchronously. +In this case the provider should abandon the operation and do nothing else.</p> +</div> +<div class="paragraph"> +<p>This operation should be called at the start of any I/O operation, and must +be called not more than once for a given I/O operation on a given <em>aio</em>.</p> +</div> +<div class="paragraph"> +<p>Once this function is called, if <code>true</code> is returned, then the provider MUST +guarantee that <a href="nng_aio_finish.3.html"><code>nng_aio_finish()</code></a> is called for the <em>aio</em> +exactly once, when the operation is complete or canceled.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is only for I/O providers (those actually performing +the operation such as HTTP handler functions or transport providers); ordinary +users of the <em>aio</em> should not call this function. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>true</code> +</td> +<td class="hdlist2"> +<p>The operation has been started.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>false</code> +</td> +<td class="hdlist2"> +<p>The operation cannot be started.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_cancel.3.html">nng_aio_cancel(3)</a>, +<a href="nng_aio_defer.3.html">nng_aio_defer(3)</a>, +<a href="nng_aio_finish.3.html">nng_aio_finish(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_busy.3.html b/man/v1.7.2/nng_aio_busy.3.html new file mode 100644 index 00000000..ee0fbbd0 --- /dev/null +++ b/man/v1.7.2/nng_aio_busy.3.html @@ -0,0 +1,87 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_busy(3) +--- +<h1>nng_aio_busy(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_busy - test if asynchronous I/O is busy</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_busy</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_busy()</code> function returns true if the +<em>aio</em> is currently busy performing an asynchronous I/O +operation or is executing a completion callback.</p> +</div> +<div class="paragraph"> +<p>If no operation has been started, or the operation has +been completed or canceled, and any callback has been +executed, then it returns false.</p> +</div> +<div class="paragraph"> +<p>This is the same test used internally by +<a href="nng_aio_wait.3.html"><code>nng_aio_wait()</code></a></p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Care should be taken to ensure that the <em>aio</em> object is not +freed when using this function. The caller is responsible for +coordinating any use of this with any reuse of the <em>aio</em>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>True if the <em>aio</em> is busy, false otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_abort.3.html">nng_aio_abort(3)</a>, +<a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_wait.3.html">nng_aio_wait(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_cancel.3.html b/man/v1.7.2/nng_aio_cancel.3.html new file mode 100644 index 00000000..35934b0a --- /dev/null +++ b/man/v1.7.2/nng_aio_cancel.3.html @@ -0,0 +1,88 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_cancel(3) +--- +<h1>nng_aio_cancel(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_cancel - cancel asynchronous I/O operation</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_cancel</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_cancel()</code> function aborts an operation previously started +with the handle <em>aio</em>. +If the operation is aborted, then the callback +for the handle will be called, and the function +<a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a> will return the error <code>NNG_ECANCELED</code>.</p> +</div> +<div class="paragraph"> +<p>This function does not wait for the operation to be fully aborted, but +returns immediately.</p> +</div> +<div class="paragraph"> +<p>If no operation is currently in progress (either because it has already +finished, or no operation has been started yet), then this function +has no effect.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is the same as calling +<a href="nng_aio_abort.3.html"><code>nng_aio_abort()</code></a> with the error <code>NNG_ECANCELED</code>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_abort.3.html">nng_aio_abort(3)</a>, +<a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_count.3.html b/man/v1.7.2/nng_aio_count.3.html new file mode 100644 index 00000000..5f6eefd3 --- /dev/null +++ b/man/v1.7.2/nng_aio_count.3.html @@ -0,0 +1,91 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_count(3) +--- +<h1>nng_aio_count(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_count - return number of bytes transferred</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_count</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_count()</code> returns the number of bytes transferred by the +asynchronous operation associated with the handle <em>aio</em>.</p> +</div> +<div class="paragraph"> +<p>Some asynchronous operations do not provide meaningful data for this +function; for example operations that establish connections do not +transfer user data (they may transfer protocol data though) — in this case +this function will generally return zero.</p> +</div> +<div class="paragraph"> +<p>This function is most useful when used with operations that make use of +of a scatter/gather vector (set by <a href="nng_aio_set_iov.3.html"><code>nng_aio_set_iov()</code></a>).</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The return value from this function is undefined if the operation +has not completed yet. +Either call this from the handle’s completion callback, +or after waiting for the operation to complete with +<a href="nng_aio_wait.3.html"><code>nng_aio_wait()</code></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The number of bytes transferred by the operation.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio_set_iov.3.html">nng_aio_set_iov(3)</a>, +<a href="nng_aio_wait.3.html">nng_aio_wait(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_defer.3.html b/man/v1.7.2/nng_aio_defer.3.html new file mode 100644 index 00000000..84f7a025 --- /dev/null +++ b/man/v1.7.2/nng_aio_defer.3.html @@ -0,0 +1,139 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_defer(3) +--- +<h1>nng_aio_defer(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_defer - defer asynchronous I/O operation</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-o">*</span><span class="tok-n">nng_aio_cancelfn</span><span class="tok-p">)(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">arg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">err</span><span class="tok-p">);</span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_defer</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio_cancelfn</span><span class="tok-w"> </span><span class="tok-n">fn</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">arg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_defer()</code> function marks operation associated with <em>aio</em> as +being deferred for asynchronous completion, and also registers a cancellation +function <em>fn</em> and associated argument <em>arg</em>, thereby +permitting the operation to be canceled.</p> +</div> +<div class="paragraph"> +<p>If the <em>aio</em> is being canceled, the cancellation routine <em>fn</em> will be called +with the <em>aio</em>, the <em>arg</em> specified by <code>nng_aio_defer()</code>, and an error +value in <em>err</em>, which is the reason that the operation is being canceled.</p> +</div> +<div class="paragraph"> +<p>The operation may not be cancelable; for example it may have already been +completed, or be in a state where it is no longer possible to unschedule it. +In this case, the <em>cancelfn</em> should just return without making any changes.</p> +</div> +<div class="paragraph"> +<p>If the cancellation routine successfully canceled the operation, it should +ensure that <a href="nng_aio_finish.3.html"><code>nng_aio_finish()</code></a> is called, with the +error code specified by <em>err</em>.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +It is mandatory that I/O providers call +<a href="nng_aio_finish.3.html"><code>nng_aio_finish()</code></a> +<strong>EXACTLY ONCE</strong> when they are finished with the operation. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is only for I/O providers (those actually performing +the operation such as HTTP handler functions or transport providers); ordinary +users of the <em>aio</em> should not call this function. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Care must be taken to ensure that cancellation and completion of +the routine are multi-thread safe; this will usually involve the use +of locks or other synchronization primitives. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +For operations that complete synchronously, without any need to be +deferred, the provider should not bother to call <code>nng_aio_defer()</code>, +although it is harmless if it does. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_cancel.3.html">nng_aio_cancel(3)</a>, +<a href="nng_aio_finish.3.html">nng_aio_finish(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_finish.3.html b/man/v1.7.2/nng_aio_finish.3.html new file mode 100644 index 00000000..225643ab --- /dev/null +++ b/man/v1.7.2/nng_aio_finish.3.html @@ -0,0 +1,99 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_finish(3) +--- +<h1>nng_aio_finish(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_finish - finish asynchronous I/O operation</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_finish</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">err</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_finish()</code> function marks operation associated with <em>aio</em> as +complete, with the status <em>err</em>. +This will be the result returned by +<a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>.</p> +</div> +<div class="paragraph"> +<p>This function causes the callback associated with the <em>aio</em> to called.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +It is mandatory that operation providers call this function +<strong>exactly once</strong> when they are finished with the operation. +After calling this function they <strong>must not</strong> perform any further accesses +to the <em>aio</em>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is only for I/O providers (those actually performing +the operation such as HTTP handler functions or transport providers); ordinary +users of the <em>aio</em> should not have any need for this function. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_begin.3.html">nng_aio_begin(3)</a>, +<a href="nng_aio_cancel.3.html">nng_aio_cancel(3)</a>, +<a href="nng_aio_defer.3.html">nng_aio_defer(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_free.3.html b/man/v1.7.2/nng_aio_free.3.html new file mode 100644 index 00000000..101023ec --- /dev/null +++ b/man/v1.7.2/nng_aio_free.3.html @@ -0,0 +1,83 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_free(3) +--- +<h1>nng_aio_free(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_free - free asynchronous I/O handle</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_free</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span> +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_reap</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_free()</code> function frees an allocated asynchronous I/O handle. +If any operation is in progress, the operation is canceled, and the +caller is blocked until the operation is completely canceled, to ensure +that it is safe to deallocate the handle and any associated resources. +(This is done by implicitly calling <a href="nng_aio_stop.3.html"><code>nng_aio_stop()</code></a>.)</p> +</div> +<div class="paragraph"> +<p>The <code>nng_aio_reap()</code> function is the same as <code>nng_aio_free()</code>, but does +its work in a background thread. +This can be useful to discard the <em>aio</em> object from within the callback for the <em>aio</em>.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Once either of these functions are called, the <em>aio</em> object is invalid and must not be used again. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_stop.3.html">nng_aio_stop(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_get_input.3.html b/man/v1.7.2/nng_aio_get_input.3.html new file mode 100644 index 00000000..45a4c5d5 --- /dev/null +++ b/man/v1.7.2/nng_aio_get_input.3.html @@ -0,0 +1,72 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_get_input(3) +--- +<h1>nng_aio_get_input(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_get_input - return input parameter</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_aio_get_input</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">unsigned</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">index</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_get_input()</code> function returns the value of the input parameter +previously set at <em>index</em> on <em>aio</em> with the +<a href="nng_aio_set_input.3.html"><code>nng_aio_set_input()</code></a> function.</p> +</div> +<div class="paragraph"> +<p>The valid values of <em>index</em> range from zero (0) to three (3), as no operation +currently defined can accept more than four parameters. +(This limit could increase in the future.) +If the index supplied is outside of this range, +or of the input parameter was not previously set, then <code>NULL</code> is returned.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Value previously set, or <code>NULL</code>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_get_output.3.html">nng_aio_get_output(3)</a>, +<a href="nng_aio_set_input.3.html">nng_aio_set_input(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_get_msg.3.html b/man/v1.7.2/nng_aio_get_msg.3.html new file mode 100644 index 00000000..9dc529ac --- /dev/null +++ b/man/v1.7.2/nng_aio_get_msg.3.html @@ -0,0 +1,77 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_get_msg(3) +--- +<h1>nng_aio_get_msg(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_get_msg - get message from asynchronous receive</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_aio_get_msg</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_get_msg()</code> function gets any message stored in <em>aio</em> as +either a result of a successful receive +(see <a href="nng_recv_aio.3.html"><code>nng_recv_aio()</code></a>) +or that was previously stored with <a href="nng_aio_set_msg.3.html"><code>nng_aio_set_msg()</code></a>.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +The <a href="nng_aio.5.html"><code>nng_aio</code></a> must not have an operation in progress. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_set_msg.3.html">nng_aio_set_msg(3)</a>, +<a href="nng_recv_aio.3.html">nng_recv_aio(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_get_output.3.html b/man/v1.7.2/nng_aio_get_output.3.html new file mode 100644 index 00000000..a4931523 --- /dev/null +++ b/man/v1.7.2/nng_aio_get_output.3.html @@ -0,0 +1,95 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_get_output(3) +--- +<h1>nng_aio_get_output(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_get_output - return output result</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_aio_get_output</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">unsigned</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">index</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_get_output()</code> function returns the output result at <em>index</em> +resulting from the asynchronous operation associated with <em>aio</em>.</p> +</div> +<div class="paragraph"> +<p>The type and semantics of output parameters are determined by specific +operations.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +If the <em>index</em> does not correspond to a defined output for the operation, +or the operation did not succeed, then the return value will be <code>NULL</code>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +It is an error to call this function while the <em>aio</em> is currently +in use by an active asynchronous operation, or if no operation has been +performed using the <em>aio</em> yet. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <em>index</em>th result of the operation, or <code>NULL</code>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_get_output.3.html">nng_aio_get_output(3)</a>, +<a href="nng_aio_set_input.3.html">nng_aio_set_input(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_result.3.html b/man/v1.7.2/nng_aio_result.3.html new file mode 100644 index 00000000..d9300b72 --- /dev/null +++ b/man/v1.7.2/nng_aio_result.3.html @@ -0,0 +1,103 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_result(3) +--- +<h1>nng_aio_result(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_result - return result of asynchronous operation</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_result</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_result()</code> returns the result of the operation associated +with the handle <em>aio</em>. +If the operation was successful, then 0 is returned. +Otherwise a non-zero error code is returned.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The return value from this function is undefined if the operation +has not completed yet. +Either call this from the handle’s completion +callback, or after waiting for the operation to complete with +<a href="nng_aio_wait.3.html"><code>nng_aio_wait()</code></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The result of the operation, either zero on success, or an error +number on failure.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>The operation timed out.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Various other return values are possible depending on the operation.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_abort.3.html">nng_aio_abort(3)</a>, +<a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_wait.3.html">nng_aio_wait(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_set_input.3.html b/man/v1.7.2/nng_aio_set_input.3.html new file mode 100644 index 00000000..a71321c5 --- /dev/null +++ b/man/v1.7.2/nng_aio_set_input.3.html @@ -0,0 +1,104 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_set_input(3) +--- +<h1>nng_aio_set_input(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_set_input - set input parameter</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_set_input</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">unsigned</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">index</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">param</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_set_input()</code> function sets the input parameter at <em>index</em> +to <em>param</em> for the asynchronous operation associated with <em>aio</em>.</p> +</div> +<div class="paragraph"> +<p>The type and semantics of input parameters are determined by specific +operations; the caller must supply appropriate inputs for the operation +to be performed.</p> +</div> +<div class="paragraph"> +<p>The valid values of <em>index</em> range from zero (0) to three (3), as no operation +currently defined can accept more than four parameters. +(This limit could increase in the future.)</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +If the <em>index</em> does not correspond to a defined input for the operation, +then this function will have no effect. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +It is an error to call this function while the <em>aio</em> is currently +in use by an active asynchronous operation. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>An input parameter set with this function may be retrieved later with +the <a href="nng_aio_get_input.3.html"><code>nng_aio_get_input()</code></a> function.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_get_input.3.html">nng_aio_get_input(3)</a>, +<a href="nng_aio_get_output.3.html">nng_aio_get_output(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_set_iov.3.html b/man/v1.7.2/nng_aio_set_iov.3.html new file mode 100644 index 00000000..b699f4f1 --- /dev/null +++ b/man/v1.7.2/nng_aio_set_iov.3.html @@ -0,0 +1,106 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_set_iov(3) +--- +<h1>nng_aio_set_iov(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_set_iov - set scatter/gather vector</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_set_iov</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">unsigned</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">niov</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_iov</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">iov</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_set_iov()</code> function sets a scatter/gather vector <em>iov</em> on the handle <em>aio</em>.</p> +</div> +<div class="paragraph"> +<p>The <em>iov</em> is a pointer to an array of <em>niov</em> <a href="nng_iov.5.html"><code>nng_iov</code></a> +structures, which have the following definition:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-w"> </span><span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_iov</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-w"> </span><span class="tok-n">iov_buf</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">iov_len</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-p">};</span></code></pre> +</div> +</div> +<div class="paragraph"> +<p>The <em>iov</em> is copied into storage in the <em>aio</em> itself, so that callers may use stack allocated <code>nng_iov</code> structures. +The values pointed to by the <code>iov_buf</code> members are <strong>not</strong> copied by this function though.</p> +</div> +<div class="paragraph"> +<p>A maximum of four (4) <code>nng_iov</code> members may be supplied.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Earlier versions of the library could accept longer scatter-gather lists. +However, no known consumers have ever needed a scatter-gather list longer than 4 vectors. +As a result, the implementation limit was reduced, and heap allocations which could fail were removed. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Value of specified <em>niov</em> is too large.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_cancel.3.html">nng_aio_cancel(3)</a>, +<a href="nng_aio_count.3.html">nng_aio_count(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng_iov.5.html">nng_iov(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_set_msg.3.html b/man/v1.7.2/nng_aio_set_msg.3.html new file mode 100644 index 00000000..ddb23566 --- /dev/null +++ b/man/v1.7.2/nng_aio_set_msg.3.html @@ -0,0 +1,75 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_set_msg(3) +--- +<h1>nng_aio_set_msg(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_set_msg - set message for asynchronous send</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_set_msg</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_set_msg()</code> function sets the message that will be used +for an asynchronous send operation (see <a href="nng_send_aio.3.html"><code>nng_send_aio()</code></a>).</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +The <a href="nng_aio.5.html"><code>nng_aio</code></a> must not have an operation in progress. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_get_msg.3.html">nng_aio_get_msg(3)</a>, +<a href="nng_send_aio.3.html">nng_send_aio(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_set_output.3.html b/man/v1.7.2/nng_aio_set_output.3.html new file mode 100644 index 00000000..a87d27af --- /dev/null +++ b/man/v1.7.2/nng_aio_set_output.3.html @@ -0,0 +1,91 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_set_output(3) +--- +<h1>nng_aio_set_output(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_set_output - set output result</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_set_output</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">unsigned</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">index</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">result</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_set_output()</code> function sets the output result at <em>index</em> +to <em>result</em> for the asynchronous operation associated with <em>aio</em>.</p> +</div> +<div class="paragraph"> +<p>The type and semantics of output results are determined by specific +operations; the operation must supply appropriate output results when +the operation completes successfully.</p> +</div> +<div class="paragraph"> +<p>The valid values of <em>index</em> range from zero (0) to three (3), as no operation +currently defined can return more than four results. +(This limit could increase in the future.)</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Note that attempts to set results with an <em>index</em> greater than +three (3) will be ignored. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>An output result set with this function may be retrieved later with +the <a href="nng_aio_get_output.3.html"><code>nng_aio_get_output()</code></a> function.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_finish.3.html">nng_aio_finish(3)</a>, +<a href="nng_aio_get_output.3.html">nng_aio_get_output(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_set_timeout.3.html b/man/v1.7.2/nng_aio_set_timeout.3.html new file mode 100644 index 00000000..41b7f091 --- /dev/null +++ b/man/v1.7.2/nng_aio_set_timeout.3.html @@ -0,0 +1,104 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_set_timeout(3) +--- +<h1>nng_aio_set_timeout(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_set_timeout - set asynchronous I/O timeout</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-p">;</span> +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_set_timeout</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">timeout</span><span class="tok-p">);</span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">nng_time</span><span class="tok-p">;</span> +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_set_expire</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_time</span><span class="tok-w"> </span><span class="tok-n">expiration</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_set_timeout()</code> function sets a <em>timeout</em> +for the asynchronous operation associated with <em>aio</em>. +This causes a timer to be started when the operation is actually started. +If the timer expires before the operation is completed, then it is +aborted with an error of <code>NNG_ETIMEDOUT</code>. +The <em>timeout</em> is specified as a relative number of milliseconds.</p> +</div> +<div class="paragraph"> +<p>If the timeout is <code>NNG_DURATION_INFINITE</code>, then no timeout is used. +If the timeout is <code>NNG_DURATION_DEFAULT</code>, then a "default" or socket-specific +timeout is used. +(This is frequently the same as <code>NNG_DURATION_INFINITE</code>.)</p> +</div> +<div class="paragraph"> +<p>The <code>nng_aio_set_expire()</code> function is similar to <code>nng_aio_set_timeout()</code>, but sets +an absolute expiration time based on the system clock. The <em>expiration</em> +is expressed as a number of milliseconds since some point in the past. +The <a href="nng_clock.3supp.html"><code>nng_clock()</code></a> function can be used to determine +the current value of the clock.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +As most operations involve some context switching, it is usually a good +idea to allow at least a few tens of milliseconds before timing them out — a too small timeout might not allow the operation to properly begin before +giving up! +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The value of <em>timeout</em> set for the <em>aio</em> is persistent, so that if the +handle is reused for multiple operations, they will have the same relative +timeout.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_cancel.3.html">nng_aio_cancel(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_stop.3.html b/man/v1.7.2/nng_aio_stop.3.html new file mode 100644 index 00000000..8abf58e8 --- /dev/null +++ b/man/v1.7.2/nng_aio_stop.3.html @@ -0,0 +1,90 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_stop(3) +--- +<h1>nng_aio_stop(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_stop - stop asynchronous I/O operation</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_stop</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_stop()</code> function stops the asynchronous I/O operation +associated with <em>aio</em> by aborting with <code>NNG_ECANCELED</code>, and then waits +for it to complete or to be completely aborted, and for the +callback associated with the <em>aio</em> to have completed executing.</p> +</div> +<div class="paragraph"> +<p>Further calls to +<a href="nng_aio_begin.3.html"><code>nng_aio_begin()</code></a> using this <em>aio</em> will return false.</p> +</div> +<div class="paragraph"> +<p>It is safe to call this for an <em>aio</em>, even when no operation is currently +pending for it.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +When multiple asynchronous I/O handles are in use and need to be +shut down, it is safest to stop all of them, before deallocating any of +them with <a href="nng_aio_free.3.html"><code>nng_aio_free()</code></a>, particularly if the callbacks +might attempt to reschedule additional operations. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_cancel.3.html">nng_aio_cancel(3)</a>, +<a href="nng_aio_free.3.html">nng_aio_free(3)</a>, +<a href="nng_aio_begin.3.html">nng_aio_begin(3)</a>, +<a href="nng_aio_wait.3.html">nng_aio_wait(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_aio_wait.3.html b/man/v1.7.2/nng_aio_wait.3.html new file mode 100644 index 00000000..22a8195b --- /dev/null +++ b/man/v1.7.2/nng_aio_wait.3.html @@ -0,0 +1,83 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_aio_wait(3) +--- +<h1>nng_aio_wait(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_aio_wait - wait for asynchronous I/O operation</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_aio_wait</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_aio_wait()</code> function waits for an asynchronous I/O operation +to complete. +If the operation has not been started, or has already +completed, then it returns immediately.</p> +</div> +<div class="paragraph"> +<p>If a callback was set with <em>aio</em> when it was allocated, then this +function will not be called until the callback has completed.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This function should never be called from a function that itself +is a callback of an <a href="nng_aio.5.html"><code>aio</code></a>, either this one or any other. +Doing so may result in a deadlock. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_abort.3.html">nng_aio_abort(3)</a>, +<a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_busy.3.html">nng_aio_busy(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_alloc.3.html b/man/v1.7.2/nng_alloc.3.html new file mode 100644 index 00000000..736f6b91 --- /dev/null +++ b/man/v1.7.2/nng_alloc.3.html @@ -0,0 +1,85 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_alloc(3) +--- +<h1>nng_alloc(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_alloc - allocate memory</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_alloc</span><span class="tok-p">(</span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_alloc()</code> function allocates a contiguous memory region of +at least <em>size</em> bytes. +The memory will be 64-bit aligned.</p> +</div> +<div class="paragraph"> +<p>The returned memory can be used to hold message buffers, in which +case it can be directly passed to <a href="nng_send.3.html"><code>nng_send()</code></a> using +the flag <code>NNG_FLAG_ALLOC</code>. Alternatively, it can be freed when no +longer needed using <a href="nng_free.3.html"><code>nng_free()</code></a>.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Do not use the system <code>free()</code> function to release this memory. +On some platforms this may work, but it is not guaranteed and may lead +to a crash or other undesirable and unpredictable behavior. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns a pointer to the allocated memory on success, +and <code>NULL</code> otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>No errors are returned, but a <code>NULL</code> return value should be +treated the same as <code>NNG_ENOMEM</code>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_free.3.html">nng_free(3)</a>, +<a href="nng_send.3.html">nng_send(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_bus.7.html b/man/v1.7.2/nng_bus.7.html new file mode 100644 index 00000000..66cf09c8 --- /dev/null +++ b/man/v1.7.2/nng_bus.7.html @@ -0,0 +1,124 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_bus(7) +--- +<h1>nng_bus(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_bus - bus protocol</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/bus0/bus.h></span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>bus</em> protocol provides for building mesh networks where +every peer is connected to every other peer. +In this protocol, each message sent by a node is sent to every one of +its directly connected peers.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Messages are only sent to directly connected peers. +This means that in the event that a peer is connected indirectly, it will not +receive messages. +When using this protocol to build mesh networks, it +is therefore important that a <em>fully-connected</em> mesh network be constructed. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>All message delivery in this pattern is best-effort, which means that +peers may not receive messages. +Furthermore, delivery may occur to some, +all, or none of the directly connected peers. +(Messages are not delivered when peer nodes are unable to receive.) +Hence, send operations will never block; instead if the +message cannot be delivered for any reason it is discarded.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +In order to minimize the likelihood of message loss, this protocol +should not be used for high throughput communications. +Furthermore, the more traffic <em>in aggregate</em> that occurs across the topology, +the more likely that message loss is to occur. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_socket_operations">Socket Operations</h3> +<div class="paragraph"> +<p>The <a href="nng_bus_open.3.html"><code>nng_bus0_open()</code></a> functions create a bus socket. +This socket may be used to send and receive messages. +Sending messages will attempt to deliver to each directly connected peer.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_versions">Protocol Versions</h3> +<div class="paragraph"> +<p>Only version 0 of this protocol is supported. +(At the time of writing, no other versions of this protocol have been defined.)</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_options">Protocol Options</h3> +<div class="paragraph"> +<p>The <em>bus</em> protocol has no protocol-specific options.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_headers">Protocol Headers</h3> +<div class="paragraph"> +<p>When using a <em>bus</em> socket in <a href="nng.7.html#raw_mode">raw mode</a>, received messages will +contain the incoming <a href="nng_pipe.5.html">pipe</a> ID as the sole element in the header. +If a message containing such a header is sent using a raw <em>bus</em> socket, then, +the message will be delivered to all connected pipes <em>except</em> the one +identified in the header. +This behavior is intended for use with <a href="nng_device.3.html">device</a> +configurations consisting of just a single socket. +Such configurations are useful in the creation of rebroadcasters, and this +capability prevents a message from being routed back to its source. +If no header is present, then a message is sent to all connected pipes.</p> +</div> +<div class="paragraph"> +<p>When using normal (cooked mode) <em>bus</em> sockets, no message headers are present.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_bus_open.3.html">nng_bus_open(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_bus_open.3.html b/man/v1.7.2/nng_bus_open.3.html new file mode 100644 index 00000000..eabbfb00 --- /dev/null +++ b/man/v1.7.2/nng_bus_open.3.html @@ -0,0 +1,86 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_bus_open(3) +--- +<h1>nng_bus_open(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_bus_open - create bus socket</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/bus0/bus.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_bus0_open</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_bus0_open_raw</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_bus0_open()</code> function creates a <a href="nng_bus.7.html"><em>bus</em></a> version 0 +<a href="nng_socket.5.html">socket</a> and returns it at the location pointed to by <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_bus0_open_raw()</code> function creates a <a href="nng_bus.7.html"><em>bus</em></a> version 0 +<a href="nng_socket.5.html">socket</a> in +<a href="nng.7.html#raw_mode">raw</a> mode, and returns it at the location pointed to by <em>s</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng_bus.7.html">nng_bus(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_clock.3supp.html b/man/v1.7.2/nng_clock.3supp.html new file mode 100644 index 00000000..48421729 --- /dev/null +++ b/man/v1.7.2/nng_clock.3supp.html @@ -0,0 +1,97 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_clock(3supp) +--- +<h1>nng_clock(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_clock - get time</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">nng_time</span><span class="tok-p">;</span> + +<span class="tok-n">nng_time</span><span class="tok-w"> </span><span class="tok-nf">nng_clock</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_clock()</code> returns the number of elapsed milliseconds since some +arbitrary time in the past. +The resolution of the clock depends on the underlying timing facilities +of the system. +This function may be used for timing, but applications should not expect +very fine-grained values.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +The reference time will be the same for a given program, +but different programs may have different references. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This function is intended mostly to help with setting appropriate +timeouts using <a href="nng_cv_until.3supp.html"><code>nng_cv_until()</code></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Milliseconds since reference time.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sleep_aio.3.html">nng_sleep_aio(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_cv_until.3supp.html">nng_cv_until(3supp)</a>, +<a href="nng_msleep.3supp.html">nng_msleep(3supp)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_close.3.html b/man/v1.7.2/nng_close.3.html new file mode 100644 index 00000000..c48dcb8b --- /dev/null +++ b/man/v1.7.2/nng_close.3.html @@ -0,0 +1,96 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_close(3) +--- +<h1>nng_close(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_close - close socket</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_close</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_close()</code> function closes the supplied socket, <em>s</em>. +Messages that have been submitted for sending may be flushed or delivered, +depending upon the transport.</p> +</div> +<div class="paragraph"> +<p>Further attempts to use the socket after this call returns will result +in <code>NNG_ECLOSED</code>. +Threads waiting for operations on the socket when this +call is executed may also return with an <code>NNG_ECLOSED</code> result.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Closing the socket while data is in transmission will likely lead to loss +of that data. +There is no automatic linger or flush to ensure that the socket send buffers +have completely transmitted. +It is recommended to wait a brief period after calling +<a href="nng_send.3.html"><code>nng_send()</code></a> or similar functions, before calling this +function. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> is already closed or was never opened.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_compat.3compat.html b/man/v1.7.2/nng_compat.3compat.html new file mode 100644 index 00000000..99c0db8a --- /dev/null +++ b/man/v1.7.2/nng_compat.3compat.html @@ -0,0 +1,408 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_compat(3compat) +--- +<h1>nng_compat(3compat)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_compat - compatibility with nanomsg 1.0</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> + +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/bus.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/pair.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/pipeline.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/pubsub.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/reqrep.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/survey.h></span> + +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/inproc.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/ipc.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/tcp.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/ws.h></span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +<a href="nng.7.html"><em>NNG</em></a> provides source-level compatibility for +most <em>libnanomsg</em> 1.0 applications.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This is intended to facilitate converting legacy applications to +use <em>NNG</em>. +New applications should use the newer <a href="nng.7.html"><em>NNG</em></a> API instead. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Applications making use of this must take care +to link with <a href="libnng.3.html"><em>libnng</em></a> instead of <em>libnn</em>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +While not recommended for long term use, the value returned by +<a href="nng_socket_id.3.html"><code>nng_socket_id()</code></a> can be used with these functions +just like a value returned by <a href="nn_socket.3compat.html"><code>nn_socket()</code></a>. +This can be way to facilitate incremental transition to the new API. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Some capabilities, protocols, and transports, will not be accessible +using this API, as the compatible API has no provision for expression +of certain concepts introduced in the new API. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +While reasonable efforts have been made to provide for compatibility, +some things may behave differently, and some less common parts of the +<em>libnanomsg</em> 1.0 API are not supported at this time, including certain +options and the statistics API. +See the <a href="#_caveats">Caveats</a> section below. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_compiling">Compiling</h3> +<div class="paragraph"> +<p>When compiling legacy <em>nanomsg</em> applications, it will generally be +necessary to change the include search path to add the <code>compat</code> subdirectory +of the directory where headers were installed. +For example, if <em>NNG</em> is installed in <code>$prefix</code>, then header files will +normally be located in <code>$prefix/include/nng</code>. +In this case, to build legacy <em>nanomsg</em> apps against <em>NNG</em> you would +add <code>$prefix/include/nng/compat</code> to your compiler’s search path.</p> +</div> +<div class="paragraph"> +<p>Alternatively, you can change your source code so that <code>#include</code> statements +referring to <code><nanomsg></code> instead refer to <code><nng/compat/nanomsg></code>. +For example, instead of:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/nn.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nanomsg/reqrep.h></span></code></pre> +</div> +</div> +<div class="paragraph"> +<p>you would have this:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/compat/nanomsg/nn.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/compat/nanomsg/reqrep.h></span></code></pre> +</div> +</div> +<div class="paragraph"> +<p>Legacy applications built using these methods should be linked against <em>libnng</em> +instead of <em>libnn</em>, just like any other <em>NNG</em> application.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_functions">Functions</h3> +<div class="paragraph"> +<p>The following functions are provided:</p> +</div> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<a href="nn_socket.3compat.html"><code>nn_socket()</code></a> +</td> +<td class="hdlist2"> +<p>create socket</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_getsockopt.3compat.html"><code>nn_getsockopt()</code></a> +</td> +<td class="hdlist2"> +<p>get socket option</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_setsockopt.3compat.html"><code>nn_setsockopt()</code></a> +</td> +<td class="hdlist2"> +<p>set socket option</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_bind.3compat.html"><code>nn_bind()</code></a> +</td> +<td class="hdlist2"> +<p>accept connections from remote peers</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_connect.3compat.html"><code>nn_connect()</code></a> +</td> +<td class="hdlist2"> +<p>connect to remote peer</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_send.3compat.html"><code>nn_send()</code></a> +</td> +<td class="hdlist2"> +<p>send data</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_recv.3compat.html"><code>nn_recv()</code></a> +</td> +<td class="hdlist2"> +<p>receive data</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_shutdown.3compat.html"><code>nn_shutdown()</code></a> +</td> +<td class="hdlist2"> +<p>shut down endpoint</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_close.3compat.html"><code>nn_close()</code></a> +</td> +<td class="hdlist2"> +<p>close socket</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_poll.3compat.html"><code>nn_poll()</code></a> +</td> +<td class="hdlist2"> +<p>poll sockets</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_device.3compat.html"><code>nn_device()</code></a> +</td> +<td class="hdlist2"> +<p>create forwarding device</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_recvmsg.3compat.html"><code>nn_recvmsg()</code></a> +</td> +<td class="hdlist2"> +<p>receive message</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_sendmsg.3compat.html"><code>nn_sendmsg()</code></a> +</td> +<td class="hdlist2"> +<p>send message</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_cmsg.3compat.html"><code>nn_cmsg()</code></a> +</td> +<td class="hdlist2"> +<p>message control data</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_get_statistic.3compat.html"><code>nn_get_statistic()</code></a> +</td> +<td class="hdlist2"> +<p>get statistic (stub)</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_allocmsg.3compat.html"><code>nn_allocmsg()</code></a> +</td> +<td class="hdlist2"> +<p>allocate message</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_reallocmsg.3compat.html"><code>nn_reallocmsg()</code></a> +</td> +<td class="hdlist2"> +<p>reallocate message</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_freemsg.3compat.html"><code>nn_freemsg()</code></a> +</td> +<td class="hdlist2"> +<p>free message</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_errno.3compat.html"><code>nn_errno()</code></a> +</td> +<td class="hdlist2"> +<p>return most recent error</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_strerror.3compat.html"><code>nn_strerror()</code></a> +</td> +<td class="hdlist2"> +<p>return message for error</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<a href="nn_term.3compat.html"><code>nn_term()</code></a> +</td> +<td class="hdlist2"> +<p>terminate library</p> +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_caveats">Caveats</h3> +<div class="paragraph"> +<p>The following caveats apply when using the legacy API with <em>NNG</em>.</p> +</div> +<div class="ulist"> +<ul> +<li> +<p>Socket numbers can be quite large. +The legacy <em>libnanomsg</em> attempted to reuse socket numbers, like +file descriptors in UNIX systems. +<em>NNG</em> avoids this to prevent accidental reuse or +collision after a descriptor is closed. +Consequently, socket numbers can become quite large, and should +probably not be used for array indices.</p> +</li> +<li> +<p>The following options (<code>nn_getsockopt</code>) are unsupported: +<code>NN_SNDPRIO</code>, <code>NN_RCVPRIO</code>, <code>NN_IPV4ONLY</code>. +The priority options may be supported in the future, when +the underlying capability is present in <em>NNG</em>.</p> +</li> +<li> +<p>Access to statistics using this legacy API +(<a href="nn_get_statistic.3compat.html"><code>nn_get_statistic()</code></a>) is unsupported.</p> +</li> +<li> +<p>Some transports can support longer URLs than legacy <em>libnanomsg</em> can. +It is a good idea to use short pathnames in URLs if interoperability +is a concern.</p> +</li> +<li> +<p>Only absolute paths are supported in <code>ipc://</code> URLs. +For example, <code>ipc:///tmp/mysocket</code> is acceptable, but <code>ipc://mysocket</code> is not.</p> +</li> +<li> +<p>The WebSocket transport in this implementation (<code>ws://</code> URLs) +only supports BINARY frames.</p> +</li> +<li> +<p>Some newer transports are unusable from this mode. +In particular, this legacy API offers no way to configure +TLS or ZeroTier parameters that may be required for use.</p> +</li> +<li> +<p>ABI versioning of the compatibility layer is not supported, +and the <code>NN_VERSION_</code> macros are not present.</p> +</li> +<li> +<p>Runtime symbol information is not implemented. +Specifically, there is no <code>nn_symbol()</code> function yet. +(This may be addressed later if there is a need.)</p> +</li> +<li> +<p>The TCP transport (<code>tcp://</code> URLs) does not support specifying the local +address or interface when binding. (This could be fixed in the future, +but most likely this will be available only using the new API.)</p> +</li> +<li> +<p>The values of <code>NN_RCVMAXSIZE</code> are constrained. +Specifically, values set larger than 2GB using the new API will be reported +as unlimited (<code>-1</code>) in the new API, and the value <code>0</code> will disable any +enforcement, just like <code>-1</code>. +(There is no practical reason to ever want to limit the receive size to +zero.)</p> +</li> +<li> +<p>This implementation counts buffers in terms of messages rather than bytes. +As a result, the buffer sizes accessed with <code>NN_SNDBUF</code> and <code>NN_RCVBUF</code> are +rounded up to a whole number of kilobytes, then divided by 1024, in order +to approximate buffering assuming 1 KB messages. +Few applications should need to adjust the default values.</p> +</li> +</ul> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ctx.5.html b/man/v1.7.2/nng_ctx.5.html new file mode 100644 index 00000000..15655bd3 --- /dev/null +++ b/man/v1.7.2/nng_ctx.5.html @@ -0,0 +1,246 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ctx(5) +--- +<h1>nng_ctx(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ctx - protocol context</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_ctx_s</span><span class="tok-w"> </span><span class="tok-n">nng_ctx</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>An <code>nng_ctx</code> is a handle to an underlying context object, +which keeps the protocol state for some stateful protocols. +The purpose of a separate context object is to permit applications to +share a single socket, with its various underlying +<a href="nng_dialer.5.html">dialers</a>, +<a href="nng_listener.5.html">listeners</a>, +and <a href="nng_pipe.5.html">pipes</a>, +while still benefiting from separate state tracking.</p> +</div> +<div class="paragraph"> +<p>For example, a <a href="nng_req.7.html"><em>req</em></a> context will contain the request ID +of any sent request, a timer to retry the request on failure, and so forth. +A separate context on the same socket can have similar data, but corresponding +to a completely different request.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +The <code>nng_ctx</code> structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way gives the compiler a chance to perform +accurate type checks in functions passing values of this type. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>All contexts share the same socket, and so some options, as well as the +underlying transport details, will be common to all contexts on that socket.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Not every protocol supports separate contexts. +See the protocol-specific documentation for further details about whether +contexts are supported, and details about what options are supported for +contexts. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Protocols that make use of contexts will also have a default context +that is used when the socket global operations are used. +Operations using the global context will generally not interfere with +any other contexts, except that certain socket options may affect socket +global behavior.</p> +</div> +<div class="paragraph"> +<p> +Historically, applications wanting to use a stateful protocol concurrently +would have to resort to <a href="nng.7.html#raw_mode">raw mode</a> sockets, which bypasses +much of the various protocol handling, leaving it to up to the application +to do so. +Contexts make it possible to still benefit from advanced protocol handling, +including timeouts, retries, and matching requests to responses, while doing so +concurrently.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +<a href="nng.7.html#raw_mode">Raw mode</a> sockets do not support contexts, since +there is generally no state tracked for them, and thus contexts make no sense. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Contexts are an excellent mechanism to use when building concurrent +applications, and should be used in lieu of +<a href="nng.7.html#raw_mode">raw mode</a> sockets when possible. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Use of file descriptor polling (with descriptors +obtained using the +<a href="nng_options.5.html#NNG_OPT_RECVFD"><code>NNG_OPT_RECVFD</code></a> or +<a href="nng_options.5.html#NNG_OPT_SENDFD"><code>NNG_OPT_SENDFD</code></a> options) while contexts +are in use on the same socket is not supported, and may lead to unpredictable +behavior. +These asynchronous methods should not be mixed on the same socket. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="NNG_CTX_INITIALIZER">Initialization</h3> +<div class="paragraph"> +<p>A context may be initialized using the macro <code>NNG_CTX_INITIALIZER</code> +before it is opened, to prevent confusion with valid open contexts.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_example">EXAMPLE</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The following program fragment demonstrates the use of contexts to implement +a concurrent <a href="nng_rep.7.html"><em>rep</em></a> service that simply echos messages back +to the sender.</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span> +<span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">echo_context</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-p">{</span><span class="tok-w"> </span><span class="tok-n">INIT</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">RECV</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">SEND</span><span class="tok-w"> </span><span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">state</span><span class="tok-p">;</span> +<span class="tok-p">};</span> + +<span class="tok-kt">void</span> +<span class="tok-nf">echo</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">arg</span><span class="tok-p">)</span> +<span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">echo_context</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ec</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">arg</span><span class="tok-p">;</span> + +<span class="tok-w"> </span><span class="tok-k">switch</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-n">ec</span><span class="tok-o">-></span><span class="tok-n">state</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-k">case</span><span class="tok-w"> </span><span class="tok-no">INIT</span><span class="tok-p">:</span> +<span class="tok-w"> </span><span class="tok-n">ec</span><span class="tok-o">-></span><span class="tok-n">state</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">RECV</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_ctx_recv</span><span class="tok-p">(</span><span class="tok-n">ec</span><span class="tok-o">-></span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">ec</span><span class="tok-o">-></span><span class="tok-n">aio</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-k">return</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-k">case</span><span class="tok-w"> </span><span class="tok-no">RECV</span><span class="tok-p">:</span> +<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-n">nng_aio_result</span><span class="tok-p">(</span><span class="tok-n">ec</span><span class="tok-o">-></span><span class="tok-n">aio</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-o">!=</span><span class="tok-w"> </span><span class="tok-mi">0</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-c1">// ... handle error</span> +<span class="tok-w"> </span><span class="tok-p">}</span> +<span class="tok-w"> </span><span class="tok-c1">// We reuse the message on the ec->aio</span> +<span class="tok-w"> </span><span class="tok-n">ec</span><span class="tok-o">-></span><span class="tok-n">state</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">SEND</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_ctx_send</span><span class="tok-p">(</span><span class="tok-n">ec</span><span class="tok-o">-></span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">ec</span><span class="tok-o">-></span><span class="tok-n">aio</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-k">return</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-k">case</span><span class="tok-w"> </span><span class="tok-no">SEND</span><span class="tok-p">:</span> +<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-n">nng_aio_result</span><span class="tok-p">(</span><span class="tok-n">ec</span><span class="tok-o">-></span><span class="tok-n">aio</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-o">!=</span><span class="tok-w"> </span><span class="tok-mi">0</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-c1">// ... handle error</span> +<span class="tok-w"> </span><span class="tok-p">}</span> +<span class="tok-w"> </span><span class="tok-n">ec</span><span class="tok-o">-></span><span class="tok-n">state</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">RECV</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_ctx_recv</span><span class="tok-p">(</span><span class="tok-n">ec</span><span class="tok-o">-></span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">ec</span><span class="tok-o">-></span><span class="tok-n">aio</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-k">return</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-p">}</span> +<span class="tok-p">}</span></code></pre> +</div> +</div> +<div class="paragraph"> +<p>Given the above fragment, the following example shows setting up the +service. It assumes that the <a href="nng_socket.5.html">socket</a> has already been +created and any transports set up as well with functions such as +<a href="nng_dial.3.html"><code>nng_dial()</code></a> +or <a href="nng_listen.3.html"><code>nng_listen()</code></a>.</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#define CONCURRENCY 1024</span> + +<span class="tok-n">echo_context</span><span class="tok-w"> </span><span class="tok-n">ecs</span><span class="tok-p">[</span><span class="tok-n">CONCURRENCY</span><span class="tok-p">];</span> + +<span class="tok-kt">void</span> +<span class="tok-nf">start_echo_service</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">rep_socket</span><span class="tok-p">)</span> +<span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-k">for</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">i</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">0</span><span class="tok-p">;</span><span class="tok-w"> </span><span class="tok-n">i</span><span class="tok-w"> </span><span class="tok-o"><</span><span class="tok-w"> </span><span class="tok-n">CONCURRENCY</span><span class="tok-p">;</span><span class="tok-w"> </span><span class="tok-n">i</span><span class="tok-o">++</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-c1">// error checks elided for clarity</span> +<span class="tok-w"> </span><span class="tok-n">nng_ctx_open</span><span class="tok-p">(</span><span class="tok-n">ec</span><span class="tok-p">[</span><span class="tok-n">i</span><span class="tok-p">].</span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">rep_socket</span><span class="tok-p">)</span> +<span class="tok-w"> </span><span class="tok-n">nng_aio_alloc</span><span class="tok-p">(</span><span class="tok-n">ec</span><span class="tok-p">[</span><span class="tok-n">i</span><span class="tok-p">].</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">echo</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-o">&</span><span class="tok-n">e</span><span class="tok-p">[</span><span class="tok-n">i</span><span class="tok-p">]);</span> +<span class="tok-w"> </span><span class="tok-n">ec</span><span class="tok-p">[</span><span class="tok-n">i</span><span class="tok-p">].</span><span class="tok-n">state</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">INIT</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">echo</span><span class="tok-p">(</span><span class="tok-o">&</span><span class="tok-n">ec</span><span class="tok-p">[</span><span class="tok-n">i</span><span class="tok-p">]);</span><span class="tok-w"> </span><span class="tok-c1">// start it running</span> +<span class="tok-w"> </span><span class="tok-p">}</span> +<span class="tok-p">}</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_ctx_close.3.html">nng_ctx_close(3)</a>, +<a href="nng_ctx_open.3.html">nng_ctx_open(3)</a>, +<a href="nng_ctx_get.3.html">nng_ctx_get(3)</a>, +<a href="nng_ctx_id.3.html">nng_ctx_id(3)</a>, +<a href="nng_ctx_recv.3.html">nng_ctx_recv(3)</a>, +<a href="nng_ctx_recvmsg.3.html">nng_ctx_recvmsg(3)</a>, +<a href="nng_ctx_send.3.html">nng_ctx_send(3)</a>, +<a href="nng_ctx_sendmsg.3.html">nng_ctx_sendmsg(3)</a>, +<a href="nng_ctx_set.3.html">nng_ctx_set(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ctx_close.3.html b/man/v1.7.2/nng_ctx_close.3.html new file mode 100644 index 00000000..5991a679 --- /dev/null +++ b/man/v1.7.2/nng_ctx_close.3.html @@ -0,0 +1,91 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ctx_close(3) +--- +<h1>nng_ctx_close(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ctx_close - close context</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_close</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_ctx_close()</code> function closes the context <em>ctx</em>. +Messages that have been submitted for sending may be flushed or delivered, +depending upon the transport.</p> +</div> +<div class="paragraph"> +<p>Further attempts to use the context after this call returns will result +in <code>NNG_ECLOSED</code>. +Threads waiting for operations on the context when this +call is executed may also return with an <code>NNG_ECLOSED</code> result.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Closing the socket associated with <em>ctx</em> +(using <a href="nng_close.3.html"><code>nng_close()</code></a>) also closes this context. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The context <em>ctx</em> is already closed or was never opened.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_ctx_open.3.html">nng_ctx_open(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_ctx.5.html">nng_ctx(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ctx_get.3.html b/man/v1.7.2/nng_ctx_get.3.html new file mode 100644 index 00000000..6449d44a --- /dev/null +++ b/man/v1.7.2/nng_ctx_get.3.html @@ -0,0 +1,229 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ctx_get(3) +--- +<h1>nng_ctx_get(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ctx_get - get context option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_get</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valszp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_get_bool</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">bvalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_get_int</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ivalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_get_ms</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">durp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_get_size</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">zp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_get_string</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">strp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_get_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u64p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <code>nng_ctx_get()</code> functions are used to retrieve option values for +the <a href="nng_ctx.5.html">context</a> <em>ctx</em>. +The actual options that may be retrieved in this way vary. +A number of them are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Context options are protocol specific. +The details will be documented with the protocol. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the context <em>ctx</em>. +The forms vary based on the type of the option they take.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_ctx_get()</code></dt> +<dd> +<p>This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in <em>val</em>, +and the size of the buffer shall be stored at the location referenced by +<em>valszp</em>.<br> +<br> +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>valszp</em>. +If the caller’s buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in <em>valszp</em> does not exceed the original buffer size.<br> +<br> +It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>valszp</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_ctx_get_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The value will be stored at <em>ivalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_get_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The value will be stored at <em>ivalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_get_ms()</code></dt> +<dd> +<p>This function is used to retrieve time <a href="nng_duration.5.html">durations</a> +(such as timeouts), stored in <em>durp</em> as a number of milliseconds. +(The special value <code>NNG_DURATION_INFINITE</code> means an infinite amount of time, and +the special value <code>NNG_DURATION_DEFAULT</code> means a context-specific default.)</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_get_size()</code></dt> +<dd> +<p>This function is used to retrieve a size into the pointer <em>zp</em>, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_get_string()</code></dt> +<dd> +<p>This function is used to retrieve a string into <em>strp</em>. +This string is created from the source using <a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_get_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value into the value +referenced by <em>u64p</em>. +This is typically used for options related to identifiers, network +numbers, and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>s</em> does not refer to an open socket.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Size of destination <em>val</em> too small for object.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is write-only.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_ctx_set.3.html">nng_ctx_set(3)</a>, +<a href="nng_strdup.3.html">nng_strdup(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_strfree.3.html">nng_strfree(3)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_ctx.5.html">nng_ctx(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ctx_getopt.3.html b/man/v1.7.2/nng_ctx_getopt.3.html new file mode 100644 index 00000000..9db06a0d --- /dev/null +++ b/man/v1.7.2/nng_ctx_getopt.3.html @@ -0,0 +1,242 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ctx_getopt(3) +--- +<h1>nng_ctx_getopt(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ctx_getopt - get context option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_getopt</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valszp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_getopt_bool</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">bvalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_getopt_int</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ivalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_getopt_ms</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">durp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_getopt_size</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">zp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_getopt_string</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">strp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_getopt_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u64p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +These functions are deprecated. Please see <a href="nng_ctx_get.3.html">nng_ctx_get</a>. +They may not be present if the library was built with <code>NNG_ELIDE_DEPRECATED</code>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p> +The <code>nng_ctx_getopt()</code> functions are used to retrieve option values for +the <a href="nng_ctx.5.html">context</a> <em>ctx</em>. +The actual options that may be retrieved in this way vary. +A number of them are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Context options are protocol specific. +The details will be documented with the protocol. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the context <em>ctx</em>. +The forms vary based on the type of the option they take.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_ctx_getopt()</code></dt> +<dd> +<p>This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in <em>val</em>, +and the size of the buffer shall be stored at the location referenced by +<em>valszp</em>.<br> +<br> +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>valszp</em>. +If the caller’s buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in <em>valszp</em> does not exceed the original buffer size.<br> +<br> +It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>valszp</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_ctx_getopt_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The value will be stored at <em>ivalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_getopt_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The value will be stored at <em>ivalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_getopt_ms()</code></dt> +<dd> +<p>This function is used to retrieve time <a href="nng_duration.5.html">durations</a> +(such as timeouts), stored in <em>durp</em> as a number of milliseconds. +(The special value <code>NNG_DURATION_INFINITE</code> means an infinite amount of time, and +the special value <code>NNG_DURATION_DEFAULT</code> means a context-specific default.)</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_getopt_size()</code></dt> +<dd> +<p>This function is used to retrieve a size into the pointer <em>zp</em>, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_getopt_string()</code></dt> +<dd> +<p>This function is used to retrieve a string into <em>strp</em>. +This string is created from the source using <a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_getopt_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value into the value +referenced by <em>u64p</em>. +This is typically used for options related to identifiers, network +numbers, and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>s</em> does not refer to an open socket.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Size of destination <em>val</em> too small for object.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is write-only.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_ctx_setopt.3.html">nng_ctx_setopt(3)</a>, +<a href="nng_strdup.3.html">nng_strdup(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_strfree.3.html">nng_strfree(3)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_ctx.5.html">nng_ctx(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ctx_id.3.html b/man/v1.7.2/nng_ctx_id.3.html new file mode 100644 index 00000000..bf503a81 --- /dev/null +++ b/man/v1.7.2/nng_ctx_id.3.html @@ -0,0 +1,79 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ctx_id(3) +--- +<h1>nng_ctx_id(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ctx_id - return numeric context identifier</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_id</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">c</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_ctx_id()</code> function returns a positive identifier for the context <em>c</em>, +if it is valid. +Otherwise it returns <code>-1</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +A context is considered valid if it was ever opened with +<a href="nng_ctx_open.3.html"><code>nng_ctx_open()</code></a> function. +Contexts that are allocated on the stack or statically should be +initialized with the macro +<a href="nng_ctx.5.html#NNG_CTX_INITIALIZER"><code>NNG_CTX_INITIALIZER</code></a> to ensure that +they cannot be confused with a valid context before they are opened. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the positive value for the context identifier, or +<code>-1</code> if the context is invalid.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_ctx.5.html">nng_ctx(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ctx_open.3.html b/man/v1.7.2/nng_ctx_open.3.html new file mode 100644 index 00000000..9a5db4f6 --- /dev/null +++ b/man/v1.7.2/nng_ctx_open.3.html @@ -0,0 +1,126 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ctx_open(3) +--- +<h1>nng_ctx_open(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ctx_open - create context</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_open</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ctxp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_ctx_open()</code> function creates a separate context to be used with +the socket <em>s</em>, +and returns it at the location pointed by <em>ctxp</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Not every protocol supports creation of separate contexts. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Contexts allow the independent and concurrent use of stateful operations +using the same socket. +For example, two different contexts created on a <a href="nng_rep.7.html"><em>rep</em></a> +socket can each receive requests, and send replies to them, without any +regard to or interference with each other.</p> +</div> +<div class="paragraph"> +<p> +TIP: Using contexts is an excellent way to write simpler concurrent +applications, while retaining the benefits of the protocol-specific +advanced processing, avoiding the need to bypass that with +<a href="nng.7.html#raw_mode">raw mode</a> sockets.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Use of contexts with <a href="nng.7.html#raw_mode">raw mode</a> sockets is +nonsensical, and not supported. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol does not support separate contexts, or the socket was opened in raw mode.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_ctx_close.3.html">nng_ctx_close(3)</a>, +<a href="nng_ctx_getopt.3.html">nng_ctx_getopt(3)</a>, +<a href="nng_ctx_recv.3.html">nng_ctx_recv(3)</a>, +<a href="nng_ctx_send.3.html">nng_ctx_send(3)</a>, +<a href="nng_ctx_setopt.3.html">nng_ctx_setopt(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_ctx.5.html">nng_ctx(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng_rep.7.html">nng_rep(7)</a>, +<a href="nng_req.7.html">nng_req(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ctx_recv.3.html b/man/v1.7.2/nng_ctx_recv.3.html new file mode 100644 index 00000000..387925a0 --- /dev/null +++ b/man/v1.7.2/nng_ctx_recv.3.html @@ -0,0 +1,157 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ctx_recv(3) +--- +<h1>nng_ctx_recv(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ctx_recv - receive message using context asynchronously</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_recv</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_ctx_recv()</code> receives a <a href="nng_msg.5.html">message</a> using the +<a href="nng_ctx.5.html">context</a> <em>s</em> asynchronously.</p> +</div> +<div class="paragraph"> +<p>When a message is successfully received by the context, it is +stored in the <em>aio</em> by an internal call equivalent to +<a href="nng_aio_set_msg.3.html"><code>nng_aio_set_msg()</code></a>, then the completion +callback on the <em>aio</em> is executed. +In this case, <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a> will +return zero. +The callback function is responsible for retrieving the message +and disposing of it appropriately.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Failing to accept and dispose of messages in this +case can lead to memory leaks. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>If for some reason the asynchronous receive cannot be completed +successfully (including by being canceled or timing out), then +the callback will still be executed, +but <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a> will be non-zero.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The semantics of what receiving a message means varies from protocol to +protocol, so examination of the protocol documentation is encouraged. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None. (The operation completes asynchronously.)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was aborted.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The context <em>ctx</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol for context <em>ctx</em> does not support receiving.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The context <em>ctx</em> cannot receive data in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>The receive timeout expired.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_get_msg.3.html">nng_aio_get_msg(3)</a>, +<a href="nng_aio_set_msg.3.html">nng_aio_set_msg(3)</a>, +<a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng_ctx.5.html">nng_ctx(5)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ctx_recvmsg.3.html b/man/v1.7.2/nng_ctx_recvmsg.3.html new file mode 100644 index 00000000..56d85ebe --- /dev/null +++ b/man/v1.7.2/nng_ctx_recvmsg.3.html @@ -0,0 +1,148 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ctx_recvmsg(3) +--- +<h1>nng_ctx_recvmsg(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ctx_recvmsg - receive message using socket</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_recvmsg</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">msgp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_ctx_recvmsg()</code> receives a message on context <em>ctx</em>, storing the +received message at the location pointed to by <em>msgp</em>.</p> +</div> +<div class="paragraph"> +<p>The <em>flags</em> may contain the following value:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_FLAG_NONBLOCK</code></dt> +<dd> +<p>The function returns immediately, even if no message is available. +Without this flag, the function will wait until a message is receivable +on the context <em>ctx</em>, or any configured timer expires.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The semantics of what receiving a message means vary from protocol to +protocol, so examination of the protocol documentation is encouraged. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EAGAIN</code> +</td> +<td class="hdlist2"> +<p>The operation would block, but <code>NNG_FLAG_NONBLOCK</code> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The context or socket is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid set of <em>flags</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol does not support receiving.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The context cannot receive data in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>The operation timed out.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_ctx_open.3.html">nng_ctx_open(3)</a>, +<a href="nng_ctx_recv.3.html">nng_ctx_recv(3)</a>, +<a href="nng_ctx_sendmsg.3.html">nng_ctx_sendmsg(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_ctx.5.html">nng_ctx(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ctx_send.3.html b/man/v1.7.2/nng_ctx_send.3.html new file mode 100644 index 00000000..9ad9ca70 --- /dev/null +++ b/man/v1.7.2/nng_ctx_send.3.html @@ -0,0 +1,189 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ctx_send(3) +--- +<h1>nng_ctx_send(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ctx_send - send message using context asynchronously</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_send</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_ctx_send()</code> sends a <a href="nng_msg.5.html">message</a> using the +<a href="nng_ctx.5.html">context</a> <em>ctx</em> asynchronously.</p> +</div> +<div class="paragraph"> +<p>The message to send must have previously been set on the <em>aio</em> +using the <a href="nng_aio_set_msg.3.html"><code>nng_aio_set_msg()</code></a> function. +The function assumes ownership of the message.</p> +</div> +<div class="paragraph"> +<p>If the message was successfully queued for delivery to the socket, +then the <em>aio</em> will be completed, and <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a> +will return zero. +In this case the socket will dispose of the message when it is finished with it.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The operation will be completed, and the callback associated +with the <em>aio</em> executed, as soon as the socket accepts the message +for sending. +This does <em>not</em> indicate that the message was actually delivered, as it +may still be buffered in the sending socket, buffered in the receiving +socket, or in flight over physical media. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>If the operation fails for any reason (including cancellation or timeout), +then the <em>aio</em> callback will be executed and +<a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a> will return a non-zero error status. +In this case, the callback has a responsibility to retrieve the message from +the <em>aio</em> with <a href="nng_aio_get_msg.3.html"><code>nng_aio_get_msg()</code></a> and dispose of +it appropriately. +(This may include retrying the send operation on the same or a different +socket, or deallocating the message with <a href="nng_msg_free.3.html"><code>nng_msg_free()</code></a>.)</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The semantics of what sending a message means varies from protocol to +protocol, so examination of the protocol documentation is encouraged. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Context send operations are asynchronous. +If a synchronous operation is needed, one can be constructed by using a +<code>NULL</code> callback on the <em>aio</em> and then waiting for the operation using +<a href="nng_aio_wait.3.html"><code>nng_aio_wait()</code></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None. (The operation completes asynchronously.)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was aborted.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The context <em>ctx</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EMSGSIZE</code> +</td> +<td class="hdlist2"> +<p>The message is too large.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol for context <em>ctx</em> does not support sending.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The context <em>ctx</em> cannot send data in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>The send timeout expired.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_get_msg.3.html">nng_aio_get_msg(3)</a>, +<a href="nng_aio_set_msg.3.html">nng_aio_set_msg(3)</a>, +<a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng_ctx.5.html">nng_ctx(5)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ctx_sendmsg.3.html b/man/v1.7.2/nng_ctx_sendmsg.3.html new file mode 100644 index 00000000..02ba48d1 --- /dev/null +++ b/man/v1.7.2/nng_ctx_sendmsg.3.html @@ -0,0 +1,187 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ctx_sendmsg(3) +--- +<h1>nng_ctx_sendmsg(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ctx_sendmsg - send message using context</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_sendmsg</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">c</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_ctx_sendmsg()</code> sends message <em>msg</em> using the context <em>ctx</em>.</p> +</div> +<div class="paragraph"> +<p>If the function returns zero, indicating it has accepted the message for +delivery, then the <em>msg</em> is owned by the socket <em>s</em>, and the caller +must not make any further use of it. +The socket will free the message when it is finished.</p> +</div> +<div class="paragraph"> +<p>If the function returns non-zero, then it is the caller’s responsibility +to dispose of the <em>msg</em>, which may include freeing it, sending it to +another socket, or simply trying again later.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The semantics of what sending a message means vary from protocol to +protocol, so examination of the protocol documentation is encouraged. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>flags</em> may contain the following value:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_FLAG_NONBLOCK</code></dt> +<dd> +<p>The function returns immediately, regardless of whether +the context is able to accept the data or not. +If the context is unable to accept the data (such as if backpressure exists +because the peers are consuming messages too slowly, or no peer is present), +then the function will return with <code>NNG_EAGAIN</code>. +If this flag is not specified, then the function will block if such a +condition exists.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Regardless of the presence or absence of <code>NNG_FLAG_NONBLOCK</code>, there may +be queues between the sender and the receiver. +Furthermore, there is no guarantee that the message has actually been delivered. +Finally, with some protocols, the semantic is implicitly <code>NNG_FLAG_NONBLOCK</code>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EAGAIN</code> +</td> +<td class="hdlist2"> +<p>The operation would block, but <code>NNG_FLAG_NONBLOCK</code> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The context or socket is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid set of <em>flags</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EMSGSIZE</code> +</td> +<td class="hdlist2"> +<p>The value of <em>size</em> is too large.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol does not support sending.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The context cannot send data in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>The operation timed out.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_ctx_open.3.html">nng_ctx_open(3)</a>, +<a href="nng_ctx_recvmsg.3.html">nng_ctx_recvmsg(3)</a>, +<a href="nng_ctx_send.3.html">nng_ctx_send(3)</a>, +<a href="nng_sendmsg.3.html">nng_sendmsg(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng_ctx.5.html">nng_ctx(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ctx_set.3.html b/man/v1.7.2/nng_ctx_set.3.html new file mode 100644 index 00000000..c020e175 --- /dev/null +++ b/man/v1.7.2/nng_ctx_set.3.html @@ -0,0 +1,214 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ctx_set(3) +--- +<h1>nng_ctx_set(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ctx_set - set context option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_set</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">valsz</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_set_bool</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">bval</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_set_int</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">ival</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_set_ms</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">dur</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_set_size</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">z</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_set_string</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">str</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_set_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">u64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +These functions are deprecated. Please see <a href="nng_ctx_set.3.html">nng_ctx_set</a>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p> +The <code>nng_ctx_set()</code> functions are used to configure options for +the context <em>ctx</em>. +The actual options that may be configured in this way vary, and are +specified by <em>opt</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Context options are protocol specific. +The details will be documented with the protocol. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_ctx_set()</code></dt> +<dd> +<p>This function is untyped, and can be used to configure any arbitrary data. +The <em>val</em> pointer addresses the data to copy, and <em>valsz</em> is the +size of the objected located at <em>val</em>.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_ctx_set_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The <em>bval</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_set_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The <em>ival</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_set_ms()</code></dt> +<dd> +<p>This function is used to configure time durations (such as timeouts) using +type <a href="nng_duration.5.html"><code>nng_duration</code></a>. +The duration <em>dur</em> is an integer number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_set_size()</code></dt> +<dd> +<p>This function is used to configure a size, <em>z</em>, typically for buffer sizes, +message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_set_string()</code></dt> +<dd> +<p>This function is used to pass configure a string, <em>str</em>. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a <code>NUL</code> (<code>\0</code>) byte. +(Other constraints may apply as well, see the documentation for each option +for details.)</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_set_uint64()</code></dt> +<dd> +<p>This function is used to configure a 64-bit unsigned value, <em>u64</em>. +This is typically used for options related to identifiers, network numbers, +and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>s</em> does not refer to an open socket.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The value being passed is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EREADONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is read-only.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The socket is in an inappropriate state for setting this option.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_ctx_get.3.html">nng_ctx_get(3)</a>, +<a href="nng_socket_set.3.html">nng_socket_set(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_ctx.5.html">nng_ctx(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ctx_setopt.3.html b/man/v1.7.2/nng_ctx_setopt.3.html new file mode 100644 index 00000000..a8ebad8a --- /dev/null +++ b/man/v1.7.2/nng_ctx_setopt.3.html @@ -0,0 +1,215 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ctx_setopt(3) +--- +<h1>nng_ctx_setopt(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ctx_setopt - set context option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_setopt</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">valsz</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_setopt_bool</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">bval</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_setopt_int</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">ival</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_setopt_ms</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">dur</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_setopt_size</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">z</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_setopt_string</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">str</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ctx_setopt_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_ctx</span><span class="tok-w"> </span><span class="tok-n">ctx</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">u64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +These functions are deprecated. Please see <a href="nng_ctx_set.3.html">nng_ctx_set</a>. +They may not be present if the library was built with <code>NNG_ELIDE_DEPRECATED</code>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p> +The <code>nng_ctx_setopt()</code> functions are used to configure options for +the context <em>ctx</em>. +The actual options that may be configured in this way vary, and are +specified by <em>opt</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Context options are protocol specific. +The details will be documented with the protocol. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_ctx_setopt()</code></dt> +<dd> +<p>This function is untyped, and can be used to configure any arbitrary data. +The <em>val</em> pointer addresses the data to copy, and <em>valsz</em> is the +size of the objected located at <em>val</em>.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_ctx_setopt_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The <em>bval</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_setopt_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The <em>ival</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_setopt_ms()</code></dt> +<dd> +<p>This function is used to configure time durations (such as timeouts) using +type <a href="nng_duration.5.html"><code>nng_duration</code></a>. +The duration <em>dur</em> is an integer number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_setopt_size()</code></dt> +<dd> +<p>This function is used to configure a size, <em>z</em>, typically for buffer sizes, +message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_setopt_string()</code></dt> +<dd> +<p>This function is used to pass configure a string, <em>str</em>. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a <code>NUL</code> (<code>\0</code>) byte. +(Other constraints may apply as well, see the documentation for each option +for details.)</p> +</dd> +<dt class="hdlist1"><code>nng_ctx_setopt_uint64()</code></dt> +<dd> +<p>This function is used to configure a 64-bit unsigned value, <em>u64</em>. +This is typically used for options related to identifiers, network numbers, +and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>s</em> does not refer to an open socket.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The value being passed is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EREADONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is read-only.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The socket is in an inappropriate state for setting this option.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_ctx_getopt.3.html">nng_ctx_getopt(3)</a>, +<a href="nng_setopt.3.html">nng_setopt(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_ctx.5.html">nng_ctx(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_cv_alloc.3supp.html b/man/v1.7.2/nng_cv_alloc.3supp.html new file mode 100644 index 00000000..6663d78e --- /dev/null +++ b/man/v1.7.2/nng_cv_alloc.3supp.html @@ -0,0 +1,87 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_cv_alloc(3supp) +--- +<h1>nng_cv_alloc(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_cv_alloc - allocate condition variable</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_cv</span><span class="tok-w"> </span><span class="tok-n">nng_cv</span><span class="tok-p">;</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_cv_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_cv</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">cvp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_mtx</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">mtx</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_cv_alloc()</code> function allocates a condition variable, using +the mutex <em>mtx</em>, and returns it in <em>cvp</em>.</p> +</div> +<div class="paragraph"> +<p>Every condition variable is associated with a mutex, which must be +owned when a thread waits for the condition using +<a href="nng_cv_wait.3supp.html"><code>nng_cv_wait()</code></a> or +<a href="nng_cv_until.3supp.html"><code>nng_cv_until()</code></a>. +The mutex must also be owned when signaling the condition using the +<a href="nng_cv_wake.3supp.html"><code>nng_cv_wake()</code></a> or +<a href="nng_cv_wake1.3supp.html"><code>nng_cv_wake1()</code></a> functions.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_cv_free.3supp.html">nng_cv_free(3supp)</a>, +<a href="nng_cv_until.3supp.html">nng_cv_until(3supp)</a>, +<a href="nng_cv_wait.3supp.html">nng_cv_wait(3supp)</a>, +<a href="nng_cv_wake.3supp.html">nng_cv_wake(3supp)</a>, +<a href="nng_cv_wake1.3supp.html">nng_cv_wake1(3supp)</a>, +<a href="nng_mtx_alloc.3supp.html">nng_mtx_alloc(3supp)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_cv_free.3supp.html b/man/v1.7.2/nng_cv_free.3supp.html new file mode 100644 index 00000000..abdbfb83 --- /dev/null +++ b/man/v1.7.2/nng_cv_free.3supp.html @@ -0,0 +1,60 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_cv_free(3supp) +--- +<h1>nng_cv_free(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_cv_free - free condition variable</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_cv_free</span><span class="tok-p">(</span><span class="tok-n">nng_cv</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cv</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_cv_free()</code> function frees the condition variable <em>cv</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_cv_alloc.3supp.html">nng_cv_alloc(3supp)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_cv_until.3supp.html b/man/v1.7.2/nng_cv_until.3supp.html new file mode 100644 index 00000000..f830b776 --- /dev/null +++ b/man/v1.7.2/nng_cv_until.3supp.html @@ -0,0 +1,124 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_cv_until(3supp) +--- +<h1>nng_cv_until(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_cv_until - wait for condition or timeout</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_cv_until</span><span class="tok-p">(</span><span class="tok-n">nng_cv</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cv</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_time</span><span class="tok-w"> </span><span class="tok-n">when</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_cv_until()</code> waits until either the condition variable <em>cv</em> is signaled +by another thread calling either <a href="nng_cv_wake.3supp.html"><code>nng_cv_wake()</code></a> or +<a href="nng_cv_wake1.3supp.html"><code>nng_cv_wake1()</code></a>, or the system clock (as tracked +by <a href="nng_clock.3supp.html"><code>nng_clock()</code></a>) reaches <em>when</em>.</p> +</div> +<div class="paragraph"> +<p>The caller must have have ownership of the mutex that was used when +<em>cv</em> was allocated. +This function will drop the ownership of that mutex, and reacquire it +atomically just before returning to the caller. +(The waiting is done without holding the mutex.)</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Any condition may be used or checked, but the condition must be +checked, as it is possible for this function to wake up spuriously. +The best way to do this is inside a loop that repeats until the condition +tests for true. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_example">EXAMPLE</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The following example demonstrates use of this function:</p> +</div> +<div class="listingblock"> +<div class="title">Example 1: Waiting for the condition</div> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span> +<span class="tok-w"> </span><span class="tok-n">expire</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">nng_clock</span><span class="tok-p">()</span><span class="tok-w"> </span><span class="tok-o">+</span><span class="tok-w"> </span><span class="tok-mi">1000</span><span class="tok-p">;</span><span class="tok-w"> </span><span class="tok-c1">// 1 second in the future</span> +<span class="tok-w"> </span><span class="tok-n">nng_mtx_lock</span><span class="tok-p">(</span><span class="tok-n">m</span><span class="tok-p">);</span><span class="tok-w"> </span><span class="tok-c1">// assume cv was allocated using m</span> +<span class="tok-w"> </span><span class="tok-k">while</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-o">!</span><span class="tok-n">condition_true</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-n">nng_cv_until</span><span class="tok-p">(</span><span class="tok-n">cv</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">expire</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-o">==</span><span class="tok-w"> </span><span class="tok-n">NNG_ETIMEDOUT</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">printf</span><span class="tok-p">(</span><span class="tok-s">"Time out reached!</span><span class="tok-se">\n</span><span class="tok-s">"</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-k">break</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-p">}</span> +<span class="tok-w"> </span><span class="tok-p">}</span> +<span class="tok-w"> </span><span class="tok-c1">// condition_true is true</span> +<span class="tok-w"> </span><span class="tok-n">nng_mtx_unlock</span><span class="tok-p">(</span><span class="tok-n">m</span><span class="tok-p">);</span></code></pre> +</div> +</div> +<div class="listingblock"> +<div class="title">Example 2: Signaling the condition</div> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-w"> </span><span class="tok-n">nng_mtx_lock</span><span class="tok-p">(</span><span class="tok-n">m</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-n">condition_true</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-nb">true</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_cv_wake</span><span class="tok-p">(</span><span class="tok-n">cv</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-n">nng_mtx_unlock</span><span class="tok-p">(</span><span class="tok-n">m</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_cv_alloc.3supp.html">nng_cv_alloc(3supp)</a>, +<a href="nng_cv_wait.3supp.html">nng_cv_wait(3supp)</a>, +<a href="nng_cv_wake.3supp.html">nng_cv_wake(3supp)</a>, +<a href="nng_cv_wake1.3supp.html">nng_cv_wake1(3supp)</a>, +<a href="nng_mtx_alloc.3supp.html">nng_mtx_alloc(3supp)</a>, +<a href="nng_mtx_lock.3supp.html">nng_mtx_lock(3supp)</a>, +<a href="nng_mtx_unlock.3supp.html">nng_mtx_unlock(3supp)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_cv_wait.3supp.html b/man/v1.7.2/nng_cv_wait.3supp.html new file mode 100644 index 00000000..efa0ac2d --- /dev/null +++ b/man/v1.7.2/nng_cv_wait.3supp.html @@ -0,0 +1,119 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_cv_wait(3supp) +--- +<h1>nng_cv_wait(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_cv_wait - wait for condition</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_cv_wait</span><span class="tok-p">(</span><span class="tok-n">nng_cv</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cv</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_cv_wait()</code> waits for the condition variable <em>cv</em> to be signaled +by another thread calling either <a href="nng_cv_wake.3supp.html"><code>nng_cv_wake()</code></a> or +<a href="nng_cv_wake1.3supp.html"><code>nng_cv_wake1()</code></a>.</p> +</div> +<div class="paragraph"> +<p>The caller must have have ownership of the mutex that was used when +<em>cv</em> was allocated. +This function will drop the ownership of that mutex, and reacquire it +atomically just before returning to the caller. +(The waiting is done without holding the mutex.)</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Any condition may be used or checked, but the condition must be +checked, as it is possible for this function to wake up spuriously. +The best way to do this is inside a loop that repeats until the condition +tests for true. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_example">EXAMPLE</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The following example demonstrates use of this function:</p> +</div> +<div class="listingblock"> +<div class="title">Example 1: Waiting for the condition</div> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span> +<span class="tok-w"> </span><span class="tok-n">nng_mtx_lock</span><span class="tok-p">(</span><span class="tok-n">m</span><span class="tok-p">);</span><span class="tok-w"> </span><span class="tok-c1">// assume cv was allocated using m</span> +<span class="tok-w"> </span><span class="tok-k">while</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-o">!</span><span class="tok-n">condition_true</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">nng_cv_wait</span><span class="tok-p">(</span><span class="tok-n">cv</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-p">}</span> +<span class="tok-w"> </span><span class="tok-c1">// condition_true is true</span> +<span class="tok-w"> </span><span class="tok-n">nng_mtx_unlock</span><span class="tok-p">(</span><span class="tok-n">m</span><span class="tok-p">);</span></code></pre> +</div> +</div> +<div class="listingblock"> +<div class="title">Example 2: Signaling the condition</div> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-w"> </span><span class="tok-n">nng_mtx_lock</span><span class="tok-p">(</span><span class="tok-n">m</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-n">condition_true</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-nb">true</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_cv_wake</span><span class="tok-p">(</span><span class="tok-n">cv</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-n">nng_mtx_unlock</span><span class="tok-p">(</span><span class="tok-n">m</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_cv_alloc.3supp.html">nng_cv_alloc(3supp)</a>, +<a href="nng_cv_until.3supp.html">nng_cv_until(3supp)</a>, +<a href="nng_cv_wake.3supp.html">nng_cv_wake(3supp)</a>, +<a href="nng_cv_wake1.3supp.html">nng_cv_wake1(3supp)</a>, +<a href="nng_mtx_alloc.3supp.html">nng_mtx_alloc(3supp)</a>, +<a href="nng_mtx_lock.3supp.html">nng_mtx_lock(3supp)</a>, +<a href="nng_mtx_unlock.3supp.html">nng_mtx_unlock(3supp)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_cv_wake.3supp.html b/man/v1.7.2/nng_cv_wake.3supp.html new file mode 100644 index 00000000..6c1a893c --- /dev/null +++ b/man/v1.7.2/nng_cv_wake.3supp.html @@ -0,0 +1,100 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_cv_wake(3supp) +--- +<h1>nng_cv_wake(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_cv_wake - wake all waiters</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_cv_wake</span><span class="tok-p">(</span><span class="tok-n">nng_cv</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cv</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_cv_wake()</code> wakes any threads waiting for the condition variable <em>cv</em> +to be signaled in the <a href="nng_cv_wait.3supp.html"><code>nng_cv_wait()</code></a> or +<a href="nng_cv_until.3supp.html"><code>nng_cv_until()</code></a> functions.</p> +</div> +<div class="paragraph"> +<p>The caller must have have ownership of the mutex that was used when +<em>cv</em> was allocated.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The caller should already have set the condition that the waiters +will check, while holding the mutex. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This function wakes all threads, which is generally safer but can +lead to a performance problem when there are many waiters, as they are all +woken simultaneously and may contend for resources. +See <a href="nng_cv_wake1.3supp.html"><code>nng_cv_wake1()</code></a> for a solution to this problem. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_cv_alloc.3supp.html">nng_cv_alloc(3supp)</a>, +<a href="nng_cv_until.3supp.html">nng_cv_until(3supp)</a>, +<a href="nng_cv_wait.3supp.html">nng_cv_wait(3supp)</a>, +<a href="nng_cv_wake1.3supp.html">nng_cv_wake1(3supp)</a>, +<a href="nng_mtx_alloc.3supp.html">nng_mtx_alloc(3supp)</a>, +<a href="nng_mtx_lock.3supp.html">nng_mtx_lock(3supp)</a>, +<a href="nng_mtx_unlock.3supp.html">nng_mtx_unlock(3supp)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_cv_wake1.3supp.html b/man/v1.7.2/nng_cv_wake1.3supp.html new file mode 100644 index 00000000..29e2ef96 --- /dev/null +++ b/man/v1.7.2/nng_cv_wake1.3supp.html @@ -0,0 +1,100 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_cv_wake1(3supp) +--- +<h1>nng_cv_wake1(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_cv_wake1 - wake one waiter</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_cv_wake1</span><span class="tok-p">(</span><span class="tok-n">nng_cv</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cv</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_cv_wake1()</code> wakes at most one thread waiting for the condition +variable <em>cv</em> +to be signaled in the <a href="nng_cv_wait.3supp.html"><code>nng_cv_wait()</code></a> or +<a href="nng_cv_until.3supp.html"><code>nng_cv_until()</code></a> functions.</p> +</div> +<div class="paragraph"> +<p>The caller must have have ownership of the mutex that was used when +<em>cv</em> was allocated.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The caller should already have set the condition that the waiters +will check, while holding the mutex. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The caller cannot predict which waiter will be woken, and so the design must +ensure that it is sufficient that <em>any</em> waiter be woken. +When in doubt, it is safer to use <a href="nng_cv_wake.3supp.html"><code>nng_cv_wake()</code></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_cv_alloc.3supp.html">nng_cv_alloc(3supp)</a>, +<a href="nng_cv_until.3supp.html">nng_cv_until(3supp)</a>, +<a href="nng_cv_wait.3supp.html">nng_cv_wait(3supp)</a>, +<a href="nng_cv_wake.3supp.html">nng_cv_wake(3supp)</a>, +<a href="nng_mtx_alloc.3supp.html">nng_mtx_alloc(3supp)</a>, +<a href="nng_mtx_lock.3supp.html">nng_mtx_lock(3supp)</a>, +<a href="nng_mtx_unlock.3supp.html">nng_mtx_unlock(3supp)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_device.3.html b/man/v1.7.2/nng_device.3.html new file mode 100644 index 00000000..809836e1 --- /dev/null +++ b/man/v1.7.2/nng_device.3.html @@ -0,0 +1,204 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_device(3) +--- +<h1>nng_device(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_device - message forwarding device</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_device</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s1</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s2</span><span class="tok-p">);</span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_device_aio</span><span class="tok-p">(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s1</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s2</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_device()</code> and <code>nng_device_aio()</code> functions forward messages received from one +<a href="nng_socket.5.html">socket</a> <em>s1</em> to another socket <em>s2</em>, and vice versa.</p> +</div> +<div class="paragraph"> +<p>These functions are used to create forwarders, which can be used to create +complex network topologies to provide for improved horizontal scalability, +reliability, and isolation.</p> +</div> +<div class="paragraph"> +<p>Only <a href="nng_options.5.html#NNG_OPT_RAW">raw</a> mode sockets may be used with this +function. +These can be created using <code>_raw</code> forms of the various socket constructors, +such as <a href="nng_req_open.3.html"><code>nng_req0_open_raw()</code></a>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_device()</code> function does not return until one of the sockets +is closed. +The <code>nng_device_aio()</code> function returns immediately, and operates completely in +the background.</p> +</div> +<div class="sect2"> +<h3 id="_reflectors">Reflectors</h3> +<div class="paragraph"> +<p>One of the sockets passed may be an unopened socket initialized with +the <code>NNG_SOCKET_INITIALIZER</code> special value. +If this is the case, then the other socket must be valid, and must use +a protocol that is bidirectional and can peer with itself (such as +<a href="nng_pair.7.html"><em>pair</em></a> or +<a href="nng_bus.7.html"><em>bus</em></a>.) +In this case the device acts as a reflector or loop-back device, +where messages received from the valid socket are merely returned +to the sender.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_forwarders">Forwarders</h3> +<div class="paragraph"> +<p>When both sockets are valid, then the result is a forwarder or proxy. +In this case sockets <em>s1</em> and <em>s2</em> must be compatible with each other, +which is to say that they should represent the opposite halves of a two +protocol pattern, or both be the same protocol for a single protocol +pattern. +For example, if <em>s1</em> is a <a href="nng_pub.7.html"><em>pub</em></a> socket, then <em>s2</em> must +be a <a href="nng_sub.7.html"><em>sub</em></a> socket. +Or, if <em>s1</em> is a <a href="nng_bus.7.html"><em>bus</em></a> socket, then <em>s2</em> must also +be a <em>bus</em> socket.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_operation">Operation</h3> +<div class="paragraph"> +<p>The <code>nng_device()</code> function moves messages between the provided sockets.</p> +</div> +<div class="paragraph"> +<p>When a protocol has a backtrace style header, routing information +is present in the header of received messages, and is copied to the +header of the output bound message. +The underlying raw mode protocols supply the necessary header +adjustments to add or remove routing headers as needed. +This allows replies to be +returned to requesters, and responses to be routed back to surveyors.</p> +</div> +<div class="paragraph"> +<p>The caller of these functions is required to close the sockets when the +device is stopped.</p> +</div> +<div class="paragraph"> +<p>Additionally, some protocols have a maximum time-to-live to protect +against forwarding loops and especially amplification loops. +In these cases, the default limit (usually 8), ensures that messages will +self-terminate when they have passed through too many forwarders, +protecting the network from unlimited message amplification that can arise +through misconfiguration. +This is controlled via the <a href="nng_options.5.html#NNG_OPT_MAXTTL"><code>NNG_OPT_MAXTTL</code></a> +option.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Not all protocols have support for guarding against forwarding loops, +and even for those that do, forwarding loops can be extremely detrimental +to network performance. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Devices (forwarders and reflectors) act in best-effort delivery mode only. +If a message is received from one socket that cannot be accepted by the +other (due to backpressure or other issues), then the message is discarded. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Use the request/reply pattern, which includes automatic retries by +the requester, if reliable delivery is needed. +</td> +</tr> +</table> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function continues running, and only returns an appropriate error when +one occurs, or if one of the sockets is closed.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>At least one of the sockets is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The sockets are not compatible, or are both invalid.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_dial.3.html b/man/v1.7.2/nng_dial.3.html new file mode 100644 index 00000000..134a0df9 --- /dev/null +++ b/man/v1.7.2/nng_dial.3.html @@ -0,0 +1,202 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_dial(3) +--- +<h1>nng_dial(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_dial - create and start dialer</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dial</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">dp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_dial()</code> function creates a newly initialized +<a href="nng_dialer.5.html"><code>nng_dialer</code></a> object, +associated with socket <em>s</em>, and configured to dial the +address specified by <em>url</em>, and starts it. +If the value of <em>dp</em> is not <code>NULL</code>, then +the newly created dialer is stored at the address indicated by <em>dp</em>.</p> +</div> +<div class="paragraph"> +<p>Dialers initiate a remote connection to a listener. +Upon a successful +connection being established, they create a <a href="nng_pipe.5.html">pipe</a>, +add it to the socket, and then wait for that pipe to be closed. +When the pipe is closed, the dialer attempts to re-establish the connection. +Dialers will also periodically retry a connection automatically if an attempt +to connect asynchronously fails.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +While it is convenient to think of dialers as clients, the relationship +between the listener or dialer is orthogonal to any server or client status +that might be associated with a given protocol. +For example, a <a href="nng_req.7.html"><em>req</em></a> +socket might have associated dialers, but might also have associated listeners. +It may even have some of each at the same time! +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Normally, the first attempt to connect to the address indicated by <em>url</em> is done +synchronously, including any necessary name resolution. +As a result, a failure, such as if the connection is refused, will be returned +immediately, and no further action will be taken.</p> +</div> +<div class="paragraph"> +<p>However, if the special value <code>NNG_FLAG_NONBLOCK</code> is +supplied in <em>flags</em>, then the connection attempt is made asynchronously.</p> +</div> +<div class="paragraph"> +<p>Furthermore, if the connection was closed for a synchronously dialed +connection, the dialer will still attempt to redial asynchronously.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +While <code>NNG_FLAG_NONBLOCK</code> can help an application be more resilient, +it also generally makes diagnosing failures somewhat more difficult. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Because the dialer is started immediately, it is generally not possible +to apply extra configuration; if that is needed applications should consider +using <a href="nng_dialer_create.3.html"><code>nng_dialer_create()</code></a> and +<a href="nng_dialer_start.3.html"><code>nng_dialer_start()</code></a> instead.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>url</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNREFUSED</code> +</td> +<td class="hdlist2"> +<p>The remote peer refused the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The remote peer reset the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid set of <em>flags</em> or an invalid <em>url</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EPEERAUTH</code> +</td> +<td class="hdlist2"> +<p>Authentication or authorization failure.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EPROTO</code> +</td> +<td class="hdlist2"> +<p>A protocol error occurred.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EUNREACHABLE</code> +</td> +<td class="hdlist2"> +<p>The remote address is not reachable.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer_close.3.html">nng_dialer_close(3)</a>, +<a href="nng_dialer_create.3.html">nng_dialer_create(3)</a> +<a href="nng_dialer_start.3.html">nng_dialer_start(3)</a>, +<a href="nng_listen.3.html">nng_listen(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng_pipe.5.html">nng_pipe(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_dialer.5.html b/man/v1.7.2/nng_dialer.5.html new file mode 100644 index 00000000..9cb1d194 --- /dev/null +++ b/man/v1.7.2/nng_dialer.5.html @@ -0,0 +1,124 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_dialer(5) +--- +<h1>nng_dialer(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_dialer - dialer</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_dialer_s</span><span class="tok-w"> </span><span class="tok-n">nng_dialer</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +An <code>nng_dialer</code> is a handle to a dialer object, which is responsible for +creating a single <a href="nng_pipe.5.html"><code>nng_pipe</code></a> at a time by +establishing an outgoing connection.</p> +</div> +<div class="paragraph"> +<p>If the connection is broken, or fails, the dialer object will automatically +attempt to reconnect, and will keep doing so until the dialer or socket is +destroyed.</p> +</div> +<div class="paragraph"> +<p>Dialer objects are created by the +<a href="nng_dialer_create.3.html"><code>nng_dialer_create()</code></a> +or <a href="nng_dial.3.html"><code>nng_dial()</code></a> functions, and are always associated +with a single <a href="nng_socket.5.html"><code>nng_socket</code></a>.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +The <code>nng_dialer</code> structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way gives the compiler a chance to perform +accurate type checks in functions passing values of this type. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +A given <a href="nng_socket.5.html"><code>nng_socket</code></a> may have multiple dialer +objects, multiple <a href="nng_listener.5.html">listener</a> objects, or even some +of both. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The client/server relationship described by dialer/listener is +completely orthogonal to any similar relationship in the protocols. +For example, a <a href="nng_rep.7.html"><em>rep</em></a> socket may use a dialer +to connect to a listener on an <a href="nng_req.7.html"><em>req</em></a> socket. +This orthogonality can lead to innovative solutions to otherwise +challenging communications problems. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Dialer objects may be destroyed by the +<a href="nng_dialer_close.3.html"><code>nng_dialer_close()</code></a> function. +They are also closed when their associated socket is closed.</p> +</div> +<div class="sect2"> +<h3 id="NNG_DIALER_INITIALIZER">Initialization</h3> +<div class="paragraph"> +<p>A dialer may be initialized using the macro <code>NNG_DIALER_INITIALIZER</code> +before it is opened, to prevent confusion with valid open dialers.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dial.3.html">nng_dial(3)</a>, +<a href="nng_dialer_close.3.html">nng_dialer_close(3)</a>, +<a href="nng_dialer_create.3.html">nng_dialer_create(3)</a>, +<a href="nng_dialer_getopt.3.html">nng_dialer_getopt(3)</a>, +<a href="nng_dialer_id.3.html">nng_dialer_id(3)</a>, +<a href="nng_dialer_setopt.3.html">nng_dialer_setopt(3)</a>, +<a href="nng_dialer_start.3.html">nng_dialer_start(3)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng_pipe.5.html">nng_pipe(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_dialer_close.3.html b/man/v1.7.2/nng_dialer_close.3.html new file mode 100644 index 00000000..adee2556 --- /dev/null +++ b/man/v1.7.2/nng_dialer_close.3.html @@ -0,0 +1,84 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_dialer_close(3) +--- +<h1>nng_dialer_close(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_dialer_close - close dialer</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_close</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_dialer_close()</code> function closes the dialer <em>d</em>. +This also closes any <a href="nng_pipe.5.html"><code>nng_pipe</code></a> objects that have +been created by the dialer.</p> +</div> +<div class="paragraph"> +<p>Once this function returns, the dialer <em>d</em> and any of its resources +are deallocated. +Therefore it is an error to attempt to access <em>d</em> after +this function has returned. +(Attempts to do so will result in <code>NNG_ECLOSED</code> errors.)</p> +</div> +<div class="paragraph"> +<p>Dialers are implicitly closed when the socket they are associated with is closed.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>d</em> does not refer to an open dialer.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_close.3.html">nng_close(3)</a>, +<a href="nng_dial.3.html">nng_dial(3)</a>, +<a href="nng_dialer_create.3.html">nng_dialer_create(3)</a> +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_dialer_create.3.html b/man/v1.7.2/nng_dialer_create.3.html new file mode 100644 index 00000000..bf8fd769 --- /dev/null +++ b/man/v1.7.2/nng_dialer_create.3.html @@ -0,0 +1,143 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_dialer_create(3) +--- +<h1>nng_dialer_create(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_dialer_create - create dialer</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_create</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">dialerp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_dialer_create()</code> function creates a newly initialized +<a href="nng_dialer.5.html"><code>nng_dialer</code></a> object, associated with socket <em>s</em>, +and configured to connect to the +address specified by <em>url</em>, and stores a pointer to at the location +referenced by <em>dialerp</em>.</p> +</div> +<div class="paragraph"> +<p>Dialers initiate a remote connection to a listener. +Upon a successful +connection being established, they create a pipe, add it to the socket, +and then wait for that pipe to be closed. +When the pipe is closed, they will re-initiate the connection. +Dialers will also periodically retry a connection automatically if +an attempt to connect asynchronously +fails.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +While it is convenient to think of dialers as clients, the relationship +between the listener or dialer is orthogonal to any server or client status +that might be associated with a given protocol. +For example, a <a href="nng_req.7.html"><em>req</em></a> +socket might have associated dialers, but might also have associated listeners. +It may even have some of each at the same time! +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The dialer is not started, but may be further configured with +the <a href="nng_dialer_setopt.3.html"><code>nng_dialer_setopt()</code></a> family of functions.</p> +</div> +<div class="paragraph"> +<p>Once it is fully configured, the dialer may be started using the +<a href="nng_dialer_start.3.html"><code>nng_dialer_start()</code></a> function.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +If no specific configuration is required, consider using the +simpler <a href="nng_dial.3.html"><code>nng_dial()</code></a> function instead. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>url</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dial.3.html">nng_dial(3)</a>, +<a href="nng_dialer_close.3.html">nng_dialer_close(3)</a>, +<a href="nng_dialer_getopt.3.html">nng_dialer_getopt(3)</a>, +<a href="nng_dialer_setopt.3.html">nng_dialer_setopt(3)</a>, +<a href="nng_dialer_start.3.html">nng_dialer_start(3)</a>, +<a href="nng_listener_create.3.html">nng_listener_create(3)</a> +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_dialer_get.3.html b/man/v1.7.2/nng_dialer_get.3.html new file mode 100644 index 00000000..684d9fa4 --- /dev/null +++ b/man/v1.7.2/nng_dialer_get.3.html @@ -0,0 +1,237 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_dialer_get(3) +--- +<h1>nng_dialer_get(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_dialer_get - get dialer option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_get</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valszp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_get_bool</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">bvalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_get_int</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ivalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_get_ms</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">durp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_get_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_get_size</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">zp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_get_addr</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sap</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_get_string</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">strp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_get_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u64p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <code>nng_dialer_get()</code> functions are used to retrieve option values for +the <a href="nng_dialer.5.html">dialer</a> <em>d</em>. +The actual options that may be retrieved in this way +vary, and many are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally some transport-specific options are documented with the transports themselves.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the dialer <em>d</em>. +The forms vary based on the type of the option they take.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_dialer_get()</code></dt> +<dd> +<p>This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in <em>val</em>, +and the size of the buffer shall be stored at the location referenced +by <em>valszp</em>.<br> +<br> +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>valszp</em>. +If the caller’s buffer is not large +enough to hold the entire object, then the copy is truncated. +Therefore the caller should validate that the returned size in <em>valszp</em> does not +exceed the original buffer size to check for truncation.<br> +<br> +It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>valszp</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_dialer_get_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The value will be stored at <em>bvalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_get_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The value will be stored at <em>ivalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_get_ms()</code></dt> +<dd> +<p>This function is used to retrieve time <a href="nng_duration.5.html">durations</a> +(such as timeouts), stored in <em>durp</em> as a number of milliseconds. +(The special value <code>NNG_DURATION_INFINITE</code> means an infinite amount of time, and +the special value <code>NNG_DURATION_DEFAULT</code> means a context-specific default.)</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_get_ptr()</code></dt> +<dd> +<p>This function is used to retrieve a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_get_size()</code></dt> +<dd> +<p>This function is used to retrieve a size into the pointer <em>zp</em>, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_get_addr()</code></dt> +<dd> +<p>This function is used to retrieve an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +into the value referenced by <em>sap</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_get_string()</code></dt> +<dd> +<p>This function is used to retrieve a string into <em>strp</em>. +This string is created from the source using <a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_get_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value into the value +referenced by <em>u64p</em>. +This is typically used for options related to identifiers, network +numbers, and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>d</em> does not refer to an open dialer.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Size of destination <em>val</em> too small for object.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is write-only.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer_create.3.html">nng_dialer_create(3)</a> +<a href="nng_dialer_set.3.html">nng_dialer_set(3)</a> +<a href="nng_strdup.3.html">nng_strdup(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_strfree.3.html">nng_strfree(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_dialer_getopt.3.html b/man/v1.7.2/nng_dialer_getopt.3.html new file mode 100644 index 00000000..108cef0d --- /dev/null +++ b/man/v1.7.2/nng_dialer_getopt.3.html @@ -0,0 +1,250 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_dialer_getopt(3) +--- +<h1>nng_dialer_getopt(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_dialer_getopt - get dialer option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_getopt</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valszp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_getopt_bool</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">bvalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_getopt_int</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ivalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_getopt_ms</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">durp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_getopt_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_getopt_size</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">zp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_getopt_sockaddr</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sap</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_getopt_string</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">strp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_getopt_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u64p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +These functions are deprecated. Please see <a href="nng_dialer_get.3.html">nng_dialer_get</a>. +They may not be present if the library was built with <code>NNG_ELIDE_DEPRECATED</code>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p> +The <code>nng_dialer_getopt()</code> functions are used to retrieve option values for +the <a href="nng_dialer.5.html">dialer</a> <em>d</em>. +The actual options that may be retrieved in this way +vary, and many are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally some transport-specific options are documented with the transports themselves.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the dialer <em>d</em>. +The forms vary based on the type of the option they take.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_dialer_getopt()</code></dt> +<dd> +<p>This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in <em>val</em>, +and the size of the buffer shall be stored at the location referenced +by <em>valszp</em>.<br> +<br> +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>valszp</em>. +If the caller’s buffer is not large +enough to hold the entire object, then the copy is truncated. +Therefore the caller should validate that the returned size in <em>valszp</em> does not +exceed the original buffer size to check for truncation.<br> +<br> +It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>valszp</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_dialer_getopt_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The value will be stored at <em>bvalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_getopt_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The value will be stored at <em>ivalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_getopt_ms()</code></dt> +<dd> +<p>This function is used to retrieve time <a href="nng_duration.5.html">durations</a> +(such as timeouts), stored in <em>durp</em> as a number of milliseconds. +(The special value <code>NNG_DURATION_INFINITE</code> means an infinite amount of time, and +the special value <code>NNG_DURATION_DEFAULT</code> means a context-specific default.)</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_getopt_ptr()</code></dt> +<dd> +<p>This function is used to retrieve a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_getopt_size()</code></dt> +<dd> +<p>This function is used to retrieve a size into the pointer <em>zp</em>, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_getopt_sockaddr()</code></dt> +<dd> +<p>This function is used to retrieve an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +into the value referenced by <em>sap</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_getopt_string()</code></dt> +<dd> +<p>This function is used to retrieve a string into <em>strp</em>. +This string is created from the source using <a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_getopt_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value into the value +referenced by <em>u64p</em>. +This is typically used for options related to identifiers, network +numbers, and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>d</em> does not refer to an open dialer.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Size of destination <em>val</em> too small for object.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is write-only.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer_create.3.html">nng_dialer_create(3)</a> +<a href="nng_dialer_setopt.3.html">nng_dialer_setopt(3)</a> +<a href="nng_strdup.3.html">nng_strdup(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_strfree.3.html">nng_strfree(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_dialer_id.3.html b/man/v1.7.2/nng_dialer_id.3.html new file mode 100644 index 00000000..c6da5b1d --- /dev/null +++ b/man/v1.7.2/nng_dialer_id.3.html @@ -0,0 +1,80 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_dialer_id(3) +--- +<h1>nng_dialer_id(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_dialer_id - return numeric dialer identifier</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_id</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_dialer_id()</code> function returns a positive identifier for the dialer <em>d</em>, +if it is valid. +Otherwise it returns <code>-1</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +A dialer is considered valid if it was ever created with the +<a href="nng_dialer_create.3.html"><code>nng_dialer_create()</code></a> or +<a href="nng_dial.3.html"><code>nng_dial()</code></a> functions. +Dialers that are allocated on the stack or statically should be +initialized with the macro +<a href="nng_ctx.5.html#NNG_DIALER_INITIALIZER"><code>NNG_DIALER_INITIALIZER</code></a> to ensure that +they cannot be confused with a valid dialer before they are created properly. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the positive value for the dialer identifier, or +<code>-1</code> if the dialer is invalid.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_dialer_set.3.html b/man/v1.7.2/nng_dialer_set.3.html new file mode 100644 index 00000000..61d33486 --- /dev/null +++ b/man/v1.7.2/nng_dialer_set.3.html @@ -0,0 +1,244 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_dialer_set(3) +--- +<h1>nng_dialer_set(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_dialer_set - set dialer option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_set</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">valsz</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_set_bool</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">bval</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_set_int</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">ival</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_set_ms</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">dur</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_set_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_set_size</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">z</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_set_string</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">str</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_set_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">u64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <code>nng_dialer_set()</code> functions are used to configure options for +the <a href="nng_dialer.5.html">dialer</a> <em>d</em>. +The actual options that may be configured in this way +vary, and many are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally some transport-specific options are documented with the transports themselves.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Once a dialer has started, it is generally not possible to change +its configuration. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is configured on the dialer <em>d</em>.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_dialer_set()</code></dt> +<dd> +<p>This function is untyped, and can be used to configure any arbitrary data. +The <em>val</em> pointer addresses the data to copy, and <em>valsz</em> is the +size of the objected located at <em>val</em>.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_dialer_set_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The <em>bval</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_set_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The <em>ival</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_set_ms()</code></dt> +<dd> +<p>This function is used to configure time durations (such as timeouts) using +type <a href="nng_duration.5.html"><code>nng_duration</code></a>. +The duration <em>dur</em> is an integer number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_set_ptr()</code></dt> +<dd> +<p>This function is used to pass a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed by other functions. +For example, TLS configuration objects created with +(<a href="nng_tls_config_alloc.3tls.html"><code>nng_tls_config_alloc()</code></a>) +can be passed this way.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_dialer_set_size()</code></dt> +<dd> +<p>This function is used to configure a size, <em>z</em>, typically for buffer sizes, +message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_set_string()</code></dt> +<dd> +<p>This function is used to pass configure a string, <em>str</em>. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a <code>NUL</code> (<code>\0</code>) byte. +(Other constraints may apply as well, see the documentation for each option +for details.)</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_set_uint64()</code></dt> +<dd> +<p>This function is used to configure a 64-bit unsigned value, <em>u64</em>. +This is typically used for options related to identifiers, network numbers, +and such.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>d</em> does not refer to an open dialer.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The value being passed is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EREADONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is read-only.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The dialer <em>d</em> is already started.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer_create.3.html">nng_dialer_create(3)</a> +<a href="nng_dialer_get.3.html">nng_dialer_get(3)</a> +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_dialer_setopt.3.html b/man/v1.7.2/nng_dialer_setopt.3.html new file mode 100644 index 00000000..4f0e8c81 --- /dev/null +++ b/man/v1.7.2/nng_dialer_setopt.3.html @@ -0,0 +1,258 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_dialer_setopt(3) +--- +<h1>nng_dialer_setopt(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_dialer_setopt - set dialer option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_setopt</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">valsz</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_setopt_bool</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">bval</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_setopt_int</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">ival</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_setopt_ms</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">dur</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_setopt_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_setopt_size</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">z</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_setopt_string</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">str</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_setopt_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">u64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +These functions are deprecated. Please see <a href="nng_dialer_set.3.html">nng_dialer_set</a>. +They may not be present if the library was built with <code>NNG_ELIDE_DEPRECATED</code>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p> +The <code>nng_dialer_setopt()</code> functions are used to configure options for +the <a href="nng_dialer.5.html">dialer</a> <em>d</em>. +The actual options that may be configured in this way +vary, and many are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally some transport-specific options are documented with the +transports themselves.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Once a dialer has started, it is generally not possible to change +its configuration. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is configured on the dialer <em>d</em>.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_dialer_setopt()</code></dt> +<dd> +<p>This function is untyped, and can be used to configure any arbitrary data. +The <em>val</em> pointer addresses the data to copy, and <em>valsz</em> is the +size of the objected located at <em>val</em>.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_dialer_setopt_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The <em>bval</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_setopt_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The <em>ival</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_setopt_ms()</code></dt> +<dd> +<p>This function is used to configure time durations (such as timeouts) using +type <a href="nng_duration.5.html"><code>nng_duration</code></a>. +The duration <em>dur</em> is an integer number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_setopt_ptr()</code></dt> +<dd> +<p>This function is used to pass a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed by other functions. +For example, TLS configuration objects created with +(<a href="nng_tls_config_alloc.3tls.html"><code>nng_tls_config_alloc()</code></a>) +can be passed this way.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_dialer_setopt_size()</code></dt> +<dd> +<p>This function is used to configure a size, <em>z</em>, typically for buffer sizes, +message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_setopt_string()</code></dt> +<dd> +<p>This function is used to pass configure a string, <em>str</em>. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a <code>NUL</code> (<code>\0</code>) byte. +(Other constraints may apply as well, see the documentation for each option +for details.)</p> +</dd> +<dt class="hdlist1"><code>nng_dialer_setopt_uint64()</code></dt> +<dd> +<p>This function is used to configure a 64-bit unsigned value, <em>u64</em>. +This is typically used for options related to identifiers, network numbers, +and such.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>d</em> does not refer to an open dialer.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The value being passed is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EREADONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is read-only.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The dialer <em>d</em> is already started.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer_create.3.html">nng_dialer_create(3)</a> +<a href="nng_dialer_getopt.3.html">nng_dialer_getopt(3)</a> +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_dialer_start.3.html b/man/v1.7.2/nng_dialer_start.3.html new file mode 100644 index 00000000..cf7128e0 --- /dev/null +++ b/man/v1.7.2/nng_dialer_start.3.html @@ -0,0 +1,182 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_dialer_start(3) +--- +<h1>nng_dialer_start(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_dialer_start - start dialer</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_dialer_start</span><span class="tok-p">(</span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_dialer_start()</code> function starts the dialer <em>d</em>.</p> +</div> +<div class="paragraph"> +<p>This causes the dialer to start connecting to the address with which it was +created.</p> +</div> +<div class="paragraph"> +<p>When a connection is established, it results in a pipe being created, +which will be attached to the dialer’s socket.</p> +</div> +<div class="paragraph"> +<p>Normally, the first attempt to connect to the dialer’s address is done +synchronously, including any necessary name resolution. +As a result, a failure, such as if the connection is refused, will be returned +immediately, and no further action will be taken.</p> +</div> +<div class="paragraph"> +<p>However, if the special value <code>NNG_FLAG_NONBLOCK</code> is +supplied in <em>flags</em>, then the connection attempt is made asynchronously.</p> +</div> +<div class="paragraph"> +<p>Furthermore, if the connection was closed for a synchronously dialed +connection, the dialer will still attempt to redial asynchronously.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +While <code>NNG_FLAG_NONBLOCK</code> can help an application be more resilient, +it also generally makes diagnosing failures somewhat more difficult. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Once a dialer has started, it is generally not possible to change +its configuration.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>url</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNREFUSED</code> +</td> +<td class="hdlist2"> +<p>The remote peer refused the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The remote peer reset the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid set of <em>flags</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EPEERAUTH</code> +</td> +<td class="hdlist2"> +<p>Authentication or authorization failure.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EPROTO</code> +</td> +<td class="hdlist2"> +<p>A protocol error occurred.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The dialer <em>d</em> is already started.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EUNREACHABLE</code> +</td> +<td class="hdlist2"> +<p>The remote address is not reachable.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dial.3.html">nng_dial(3)</a>, +<a href="nng_dialer_create.3.html">nng_dialer_create(3)</a> +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_duration.5.html b/man/v1.7.2/nng_duration.5.html new file mode 100644 index 00000000..06d5f0e6 --- /dev/null +++ b/man/v1.7.2/nng_duration.5.html @@ -0,0 +1,68 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_duration(5) +--- +<h1>nng_duration(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_duration - relative time in milliseconds</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-kt">int32_t</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-p">;</span> + +<span class="tok-cp">#define NNG_DURATION_INFINITE (-1)</span> +<span class="tok-cp">#define NNG_DURATION_DEFAULT (-2)</span> +<span class="tok-cp">#define NNG_DURATION_ZERO (0)</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>An <code>nng_duration</code> is a relative time, measured in +milliseconds. +This type is most often used in conjunction with timers and timeouts.</p> +</div> +<div class="paragraph"> +<p>A couple of special values have been set aside, and carry special meanings.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_DURATION_DEFAULT</code></dt> +<dd> +<p>Indicates a context-specific default value should be used.</p> +</dd> +<dt class="hdlist1"><code>NNG_DURATION_INFINITE</code></dt> +<dd> +<p>Effectively an infinite duration; used most often to disable timeouts.</p> +</dd> +<dt class="hdlist1"><code>NNG_DURATION_ZERO</code></dt> +<dd> +<p>Zero length duration; used to perform a single polling operation.</p> +</dd> +</dl> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_free.3.html b/man/v1.7.2/nng_free.3.html new file mode 100644 index 00000000..33bf820d --- /dev/null +++ b/man/v1.7.2/nng_free.3.html @@ -0,0 +1,91 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_free(3) +--- +<h1>nng_free(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_free - free memory</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_free</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ptr</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_free()</code> function deallocates a memory region of size <em>size</em>, +that was previously allocated by <a href="nng_alloc.3.html"><code>nng_alloc()</code></a> or +<a href="nng_recv.3.html"><code>nng_recv()</code></a> with the <code>NNG_FLAG_ALLOC</code> flag.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +It is very important that <em>size</em> match the allocation size +used to allocate the memory. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Do not attempt to use this function to deallocate memory +obtained by a call to the system <code>malloc()</code> or <code>calloc()</code> functions, +or the C++ <code>new</code> operator. +Doing so may result in unpredictable +behavior, including corruption of application memory. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_alloc.3.html">nng_alloc(3)</a>, +<a href="nng_recv.3.html">nng_recv(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_getopt.3.html b/man/v1.7.2/nng_getopt.3.html new file mode 100644 index 00000000..8e3d8b4c --- /dev/null +++ b/man/v1.7.2/nng_getopt.3.html @@ -0,0 +1,243 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_getopt(3) +--- +<h1>nng_getopt(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_getopt - get socket option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_getopt</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valszp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_getopt_bool</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">bvalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_getopt_int</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ivalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_getopt_ms</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">durp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_getopt_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_getopt_size</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">zp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_getopt_string</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">strp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_getopt_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u64p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +These functions are deprecated. Please see <a href="nng_socket_get.3.html">nng_socket_get</a>. +They may not be present if the library was built with <code>NNG_ELIDE_DEPRECATED</code>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p> +The <code>nng_getopt()</code> functions are used to retrieve option values for +the <a href="nng_socket.5.html">socket</a> <em>s</em>. +The actual options that may be retrieved in this way vary. +A number of them are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally transport-specific options and protocol-specific options are +documented with the transports and protocols themselves.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the socket <em>s</em>. +The forms vary based on the type of the option they take.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_getopt()</code></dt> +<dd> +<p>This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in <em>val</em>, +and the size of the buffer shall be stored at the location referenced by +<em>valszp</em>.</p> +<div class="paragraph"> +<p>When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>valszp</em>. +If the caller’s buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in <em>valszp</em> does not exceed the original buffer size.</p> +</div> +<div class="paragraph"> +<p>It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>valszp</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_getopt_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The value will be stored at <em>bvalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_getopt_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The value will be stored at <em>ivalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_getopt_ms()</code></dt> +<dd> +<p>This function is used to retrieve time <a href="nng_duration.5.html">durations</a> +(such as timeouts), stored in <em>durp</em> as a number of milliseconds. +(The special value <code>NNG_DURATION_INFINITE</code> means an infinite amount of time, and +the special value <code>NNG_DURATION_DEFAULT</code> means a context-specific default.)</p> +</dd> +<dt class="hdlist1"><code>nng_getopt_ptr()</code></dt> +<dd> +<p>This function is used to retrieve a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied.</p> +</dd> +<dt class="hdlist1"><code>nng_getopt_size()</code></dt> +<dd> +<p>This function is used to retrieve a size into the pointer <em>zp</em>, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_getopt_string()</code></dt> +<dd> +<p>This function is used to retrieve a string into <em>strp</em>. +This string is created from the source using <a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_getopt_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value into the value +referenced by <em>u64p</em>. +This is typically used for options related to identifiers, network +numbers, and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>s</em> does not refer to an open socket.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Size of destination <em>val</em> too small for object.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is write-only.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer_getopt.3.html">nng_dialer_getopt(3)</a>, +<a href="nng_listener_getopt.3.html">nng_listener_getopt(3)</a>, +<a href="nng_pipe_getopt.3.html">nng_pipe_getopt(3)</a>, +<a href="nng_setopt.3.html">nng_setopt(3)</a>, +<a href="nng_strdup.3.html">nng_strdup(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_strfree.3.html">nng_strfree(3)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_client_alloc.3http.html b/man/v1.7.2/nng_http_client_alloc.3http.html new file mode 100644 index 00000000..fb23720e --- /dev/null +++ b/man/v1.7.2/nng_http_client_alloc.3http.html @@ -0,0 +1,82 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_client_alloc(3http) +--- +<h1>nng_http_client_alloc(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_client_alloc - allocate HTTP client</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_client_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_http_client</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">clientp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-n">nng_url</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_client_alloc()</code> allocates an HTTP client suitable for +connecting to the server identified by <em>url</em> and stores a pointer to +it in the location referenced by <em>clientp</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_client_free.3http.html">nng_http_client_free(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_url_parse.3.html">nng_url_parse(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_client_connect.3http.html b/man/v1.7.2/nng_http_client_connect.3http.html new file mode 100644 index 00000000..2be531b3 --- /dev/null +++ b/man/v1.7.2/nng_http_client_connect.3http.html @@ -0,0 +1,157 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_client_connect(3http) +--- +<h1>nng_http_client_connect(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_client_connect - establish HTTP client connection</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_client_connect</span><span class="tok-p">(</span><span class="tok-n">nng_http_client</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">client</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_client_connect()</code> starts the process of establishing an HTTP +connection from <em>client</em> to the server that was indicated in the URL that +<em>client</em> was configured with.</p> +</div> +<div class="paragraph"> +<p>The result of the operation will be stored in the <em>aio</em> when the operation +is complete, and will be obtainable via +<a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>.</p> +</div> +<div class="paragraph"> +<p>On success, a pointer to the underlying HTTP client (type <code>nng_http_conn *</code>) +will be stored in the first output result of the <em>aio</em>, and can be +obtained by +<a href="nng_aio_get_output.3.html"><code>nng_aio_get_output()</code></a> with an <em>index</em> of zero (0).</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINVAL</code> +</td> +<td class="hdlist2"> +<p>The client is configured with an invalid address.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was aborted.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNREFUSED</code> +</td> +<td class="hdlist2"> +<p>The TCP connection was refused by the server.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The TCP connection was reset by the server.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_example">EXAMPLE</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_url</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_http_client</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">client</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_http_conn</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">conn</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">rv</span><span class="tok-p">;</span> + +<span class="tok-w"> </span><span class="tok-c1">// Error checks elided for clarity.</span> +<span class="tok-w"> </span><span class="tok-n">nng_url_parse</span><span class="tok-p">(</span><span class="tok-o">&</span><span class="tok-n">url</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-s">"http://www.google.com"</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-n">nng_aio_alloc</span><span class="tok-p">(</span><span class="tok-o">&</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-nb">NULL</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-nb">NULL</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-n">nng_http_client_alloc</span><span class="tok-p">(</span><span class="tok-o">&</span><span class="tok-n">client</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">url</span><span class="tok-p">);</span> + +<span class="tok-w"> </span><span class="tok-n">nng_http_client_connect</span><span class="tok-p">(</span><span class="tok-n">client</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">aio</span><span class="tok-p">);</span> + +<span class="tok-w"> </span><span class="tok-c1">// Wait for connection to establish (or attempt to fail).</span> +<span class="tok-w"> </span><span class="tok-n">nng_aio_wait</span><span class="tok-p">(</span><span class="tok-n">aio</span><span class="tok-p">);</span> + +<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span><span class="tok-p">((</span><span class="tok-n">rv</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">nng_aio_result</span><span class="tok-p">(</span><span class="tok-n">aio</span><span class="tok-p">))</span><span class="tok-w"> </span><span class="tok-o">!=</span><span class="tok-w"> </span><span class="tok-mi">0</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">printf</span><span class="tok-p">(</span><span class="tok-s">"Connection failed: %s</span><span class="tok-se">\n</span><span class="tok-s">"</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_strerror</span><span class="tok-p">(</span><span class="tok-n">rv</span><span class="tok-p">));</span> +<span class="tok-w"> </span><span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-k">else</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-c1">// Connection established, get it.</span> +<span class="tok-w"> </span><span class="tok-n">conn</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">nng_aio_get_output</span><span class="tok-p">(</span><span class="tok-n">aio</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-mi">0</span><span class="tok-p">);</span> + +<span class="tok-w"> </span><span class="tok-c1">// ... do something with it here</span> + +<span class="tok-w"> </span><span class="tok-c1">// Close the connection when done to avoid leaking it.</span> +<span class="tok-w"> </span><span class="tok-n">nng_http_conn_close</span><span class="tok-p">(</span><span class="tok-n">conn</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-p">}</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_get_output.3.html">nng_aio_get_output(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio_wait.3.html">nng_aio_wait(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_http_client_alloc.3http.html">nng_http_client_alloc(3http)</a>, +<a href="nng_http_conn_close.3http.html">nng_http_conn_close(3http)</a>, +<a href="nng_http_conn_read.3http.html">nng_http_conn_read(3http)</a>, +<a href="nng_http_conn_write.3http.html">nng_http_conn_write(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_client_free.3http.html b/man/v1.7.2/nng_http_client_free.3http.html new file mode 100644 index 00000000..5641e802 --- /dev/null +++ b/man/v1.7.2/nng_http_client_free.3http.html @@ -0,0 +1,76 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_client_free(3http) +--- +<h1>nng_http_client_free(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_client_free - free HTTP client</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_client_free</span><span class="tok-p">(</span><span class="tok-n">nng_http_client</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">client</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_client_free()</code> frees the HTTP client and any associated +resources referenced by <em>client</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Any connections created by +<a href="nng_http_client_connect.3http.html"><code>nng_http_client_connect()</code></a> are unaffected, +and so the caller must close those explicitly if desired. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_client_alloc.3http.html">nng_http_client_alloc(3)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_client_get_tls.3http.html b/man/v1.7.2/nng_http_client_get_tls.3http.html new file mode 100644 index 00000000..f2c03120 --- /dev/null +++ b/man/v1.7.2/nng_http_client_get_tls.3http.html @@ -0,0 +1,100 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_client_get_tls(3http) +--- +<h1>nng_http_client_get_tls(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_client_get_tls - get HTTP client TLS configuration</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_client_get_tls</span><span class="tok-p">(</span><span class="tok-n">nng_http_client</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">client</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">cfgp</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_client_get_tls()</code> obtains the TLS configuration of <em>client</em> and +saves a pointer to it in the address referenced by <em>cfgp</em>.</p> +</div> +<div class="paragraph"> +<p>The object will be returned with an extra hold (see +<a href="nng_tls_config_hold.3tls.html"><code>nng_tls_config_hold()</code></a>) +placed on it on behalf of the caller. +The caller should free this hold by calling +<a href="nng_tls_config_free.3tls.html"><code>nng_tls_config_free()</code></a> with it is done +with the TLS configuration.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>TLS not configured on client.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>Either HTTP or TLS not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_client_alloc.3http.html">nng_http_client_alloc(3http)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_client_set_tls.3http.html">nng_http_client_set_tls(3http)</a>, +<a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_tls_config_free.3tls.html">nng_tls_config_free(3tls)</a>, +<a href="nng_tls_config_hold.3tls.html">nng_tls_config_hold(3tls)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_client_set_tls.3http.html b/man/v1.7.2/nng_http_client_set_tls.3http.html new file mode 100644 index 00000000..69049832 --- /dev/null +++ b/man/v1.7.2/nng_http_client_set_tls.3http.html @@ -0,0 +1,111 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_client_set_tls(3http) +--- +<h1>nng_http_client_set_tls(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_client_set_tls - set HTTP client TLS configuration</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_client_set_tls</span><span class="tok-p">(</span><span class="tok-n">nng_http_client</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">client</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cfg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_client_set_tls()</code> sets the TLS configuration of <em>client</em> to <em>cfg</em>.</p> +</div> +<div class="paragraph"> +<p>This change overwrites any previous TLS configuration.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This also invalidates any previously obtained values from +<a href="nng_http_client_get_tls.3http.html"><code>nng_http_client_get_tls()</code></a>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Any connections established with +<a href="nng_http_client_connect.3http.html"><code>nng_http_client_connect()</code></a> +will continue to use any TLS configuration that they were started with. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>Either HTTP or TLS not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_client_alloc.3http.html">nng_http_client_alloc(3http)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_client_get_tls.3http.html">nng_http_client_get_tls(3http)</a>, +<a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_client_transact.3http.html b/man/v1.7.2/nng_http_client_transact.3http.html new file mode 100644 index 00000000..d1c95d0a --- /dev/null +++ b/man/v1.7.2/nng_http_client_transact.3http.html @@ -0,0 +1,165 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_client_transact(3http) +--- +<h1>nng_http_client_transact(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_client_transact - perform one HTTP transaction</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_client_transact</span><span class="tok-p">(</span><span class="tok-n">nng_http_client</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">client</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_client_transact()</code> function is used to perform a complete +HTTP exchange. +It creates a new connection using <em>client</em>, performs the transaction by +sending the request <em>req</em> +(and attached body data) to the remote server, then reading the response +<em>res</em>, and finally closes the connection that it created. +The entire response is read, including any associated body, which can +subsequently be obtained using +<a href="nng_http_res_get_data.3http.html"><code>nng_http_res_get_data()</code></a>.</p> +</div> +<div class="paragraph"> +<p>This function is intended to make creation of client applications easier, +by performing multiple asynchronous operations required to complete an +entire HTTP transaction.</p> +</div> +<div class="paragraph"> +<p>A similar function, +<a href="nng_http_conn_transact.3http.html"><code>nng_http_conn_transact()</code></a>, +exists. +That function behaves similarily, but uses an existing connection, which +can be reused.</p> +</div> +<div class="admonitionblock warning"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-warning" title="Warning"></i> +</td> +<td class="content"> +If the remote server tries to send an extremely large buffer, +then a corresponding allocation will be made, which can lead to denial +of service attacks. +Client applications should take care to use this only with reasonably +trust-worthy servers. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>This function returns immediately, with no return value. +Completion of the operation is signaled via the <em>aio</em>, and the final result +may be obtained via <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>. +That result will either be zero or an error code.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The peer closed the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP operations are not supported, or peer sent chunked encoding.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EPROTO</code> +</td> +<td class="hdlist2"> +<p>An HTTP protocol error occurred.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Timeout waiting for data from the connection.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_conn_transact.3http.html">nng_http_conn_transact(3http)</a>, +<a href="nng_http_res_get_data.3http.html">nng_http_res_get_data(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_conn_close.3http.html b/man/v1.7.2/nng_http_conn_close.3http.html new file mode 100644 index 00000000..00a9f9fc --- /dev/null +++ b/man/v1.7.2/nng_http_conn_close.3http.html @@ -0,0 +1,66 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_conn_close(3http) +--- +<h1>nng_http_conn_close(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_conn_close - close HTTP connection</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_conn_close</span><span class="tok-p">(</span><span class="tok-n">nng_http_conn</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">conn</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_conn_close()</code> function closes the supplied HTTP connection <em>conn</em>, +including any disposing of any underlying file descriptors or related resources.</p> +</div> +<div class="paragraph"> +<p>Once this function, no further access to the <em>conn</em> structure may be made.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_conn_read.3http.html b/man/v1.7.2/nng_http_conn_read.3http.html new file mode 100644 index 00000000..cd98c6db --- /dev/null +++ b/man/v1.7.2/nng_http_conn_read.3http.html @@ -0,0 +1,167 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_conn_read(3http) +--- +<h1>nng_http_conn_read(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_conn_read - read from HTTP connection</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_conn_read</span><span class="tok-p">(</span><span class="tok-n">nng_http_conn</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">conn</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_conn_read()</code> function starts an asynchronous read from the +HTTP connection <em>conn</em>, into the scatter/gather vector located in the +asynchronous I/O structure <em>aio</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The <a href="nng_aio_set_iov.3.html"><code>nng_aio_set_iov()</code></a> function must have been +called first, to set the scatter/gather vector for <em>aio</em>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>This function returns immediately, with no return value. +Completion of the operation is signaled via the <em>aio</em>, +and the final result may be obtained via +<a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>. +That result will either be zero or an error code.</p> +</div> +<div class="paragraph"> +<p>The I/O operation completes as soon as at least one byte has been +read, or an error has occurred. +Therefore, the number of bytes read may be less than requested. +The actual number of bytes read can be determined with +<a href="nng_aio_count.3.html"><code>nng_aio_count()</code></a>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This function is intended to facilitate uses cases that involve changing +the protocol from HTTP, such as WebSocket. +Most applications will never need to use this function. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The peer closed the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The <em>aio</em> does not contain a valid scatter/gather vector.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP operations are not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Timeout waiting for data from the connection.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_count.3.html">nng_aio_count(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio_set_iov.3.html">nng_aio_set_iov(3)</a>, +<a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_conn_read_all.3http.html">nng_http_conn_read_all(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_conn_read_all.3http.html b/man/v1.7.2/nng_http_conn_read_all.3http.html new file mode 100644 index 00000000..64b91663 --- /dev/null +++ b/man/v1.7.2/nng_http_conn_read_all.3http.html @@ -0,0 +1,169 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_conn_read_all(3http) +--- +<h1>nng_http_conn_read_all(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_conn_read_all - read all from HTTP connection</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_conn_read_all</span><span class="tok-p">(</span><span class="tok-n">nng_http_conn</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">conn</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_conn_read_all()</code> function starts an asynchronous read from the +HTTP connection <em>conn</em>, into the scatter/gather vector located in the +asynchronous I/O structure <em>aio</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The <a href="nng_aio_set_iov.3.html"><code>nng_aio_set_iov()</code></a> function must have been +called first, to set the scatter/gather vector for <em>aio</em>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>This function returns immediately, with no return value. +Completion of the operation is signaled via the <em>aio</em>, and the final result +may be obtained via <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>. +That result will either be zero or an error code.</p> +</div> +<div class="paragraph"> +<p>The I/O operation completes only when the entire amount of data +requested has been read, or an error has occurred. +If the operation +completes successfully, then the entire requested data has been read.</p> +</div> +<div class="paragraph"> +<p>It is still possible for a partial read to complete in the event of an error. +The actual number of bytes read can be determined with +<a href="nng_aio_count.3.html"><code>nng_aio_count()</code></a>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The main purpose for this function is to facilitate reading HTTP +body content, after first determining the length of the body content +from the relevant HTTP headers (typically <code>Content-Length</code>). +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The peer closed the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The <em>aio</em> does not contain a valid scatter/gather vector.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP operations are not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Timeout waiting for data from the connection.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_count.3.html">nng_aio_count(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio_set_iov.3.html">nng_aio_set_iov(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3)</a>, +<a href="nng_http_conn_read.3http.html">nng_http_conn_read(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_conn_read_req.3http.html b/man/v1.7.2/nng_http_conn_read_req.3http.html new file mode 100644 index 00000000..7c680a4c --- /dev/null +++ b/man/v1.7.2/nng_http_conn_read_req.3http.html @@ -0,0 +1,138 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_conn_read_req(3http) +--- +<h1>nng_http_conn_read_req(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_conn_read_req - read HTTP request</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_conn_read_req</span><span class="tok-p">(</span><span class="tok-n">nng_http_conn</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">conn</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_conn_read_req()</code> function starts an asynchronous read from the +HTTP connection <em>conn</em>, reading an HTTP request into the <em>req</em>, including all +of the related headers.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Any HTTP entity/body data associated with the request is <strong>not</strong> read +automatically. +The caller should use +<a href="nng_http_conn_read_all.3http.html"><code>nng_http_conn_read_all()</code></a> +to read the entity data, based on the details of the request itself. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>This function returns immediately, with no return value. +Completion of the operation is signaled via the <em>aio</em>, and the final result +may be obtained via <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>. +That result will either be zero or an error code.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The peer closed the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP operations are not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Timeout waiting for data from the connection.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_conn_read_all.3http.html">nng_http_conn_read_all(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_conn_read_res.3http.html b/man/v1.7.2/nng_http_conn_read_res.3http.html new file mode 100644 index 00000000..85422a14 --- /dev/null +++ b/man/v1.7.2/nng_http_conn_read_res.3http.html @@ -0,0 +1,157 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_conn_read_res(3http) +--- +<h1>nng_http_conn_read_res(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_conn_read_res - read HTTP response</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_conn_read_res</span><span class="tok-p">(</span><span class="tok-n">nng_http_conn</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">conn</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_conn_read_res()</code> function starts an asynchronous read from the +HTTP connection <em>conn</em>, reading an HTTP response into the <em>res</em>, including all +of the related headers.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Any HTTP entity/body data associated with the response is <strong>not</strong> read +automatically. +The caller should use +<a href="nng_http_conn_read_all.3http.html"><code>nng_http_conn_read_all</code></a> to read the entity +data, based on the details of the response itself. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>This function returns immediately, with no return value. +Completion of +the operation is signaled via the <em>aio</em>, and the final result may be +obtained via <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>. +That result will either be zero or an error code.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Consider using the +<a href="nng_http_client_transact.3http.html"><code>nng_http_client_transact()</code></a> or +<a href="nng_http_conn_transact.3http.html"><code>nng_http_conn_transact()</code></a> functions, +which provide a simpler interface for performing a complete HTTP client +transaction. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The peer closed the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP operations are not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Timeout waiting for data from the connection.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_client_transact.3http.html">nng_http_client_transact(3http)</a>, +<a href="nng_http_conn_transact.3http.html">nng_http_conn_transact(3http)</a>, +<a href="nng_http_conn_read_all.3http.html">nng_http_conn_read_all(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_conn_transact.3http.html b/man/v1.7.2/nng_http_conn_transact.3http.html new file mode 100644 index 00000000..a48b03d2 --- /dev/null +++ b/man/v1.7.2/nng_http_conn_transact.3http.html @@ -0,0 +1,185 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_conn_transact(3http) +--- +<h1>nng_http_conn_transact(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_conn_transact - perform one HTTP transaction on connection</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_conn_transact</span><span class="tok-p">(</span><span class="tok-n">nng_http_conn</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">conn</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_conn_transact()</code> function is used to perform a complete +HTTP exchange over the connection <em>conn</em>, sending the request <em>req</em> +(and attached body data) to the remote server, and reading the response +<em>res</em>. +The entire response is read, including any associated body, which can +subsequently be obtained using +<a href="nng_http_res_get_data.3http.html"><code>nng_http_res_get_data()</code></a>.</p> +</div> +<div class="paragraph"> +<p>This function is intended to make creation of client applications easier, +by performing multiple asynchronous operations required to complete an +entire HTTP transaction.</p> +</div> +<div class="paragraph"> +<p>If an error occurs, the caller should close <em>conn</em> with +<a href="nng_http_conn_close.3http.html"><code>nng_http_conn_close()</code></a>, as it may not +necessarily be usable with other transactions.</p> +</div> +<div class="paragraph"> +<p>A similar function, +<a href="nng_http_client_transact.3http.html"><code>nng_http_client_transact()</code></a>, +exists. +That function behaves similarily, but creates a connection on demand +for the transaction, and disposes of it when finished.</p> +</div> +<div class="admonitionblock warning"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-warning" title="Warning"></i> +</td> +<td class="content"> +If the remote server tries to send an extremely large buffer, +then a corresponding allocation will be made, which can lead to denial +of service attacks. +Client applications should take care to use this only with reasonably +trust-worthy servers. +</td> +</tr> +</table> +</div> +<div class="admonitionblock warning"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-warning" title="Warning"></i> +</td> +<td class="content"> +A given connection <em>conn</em> should be used with only one +operation or transaction at a time as HTTP/1.1 has no support for +request interleaving. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>This function returns immediately, with no return value. +Completion of the operation is signaled via the <em>aio</em>, and the final result +may be obtained via <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>. +That result will either be zero or an error code.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The peer closed the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP operations are not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EPROTO</code> +</td> +<td class="hdlist2"> +<p>An HTTP protocol error occurred.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Timeout waiting for data from the connection.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_client_transact.3http.html">nng_http_client_transact(3http)</a>, +<a href="nng_http_conn_read_res.3http.html">nng_http_conn_read_res(3http)</a>, +<a href="nng_http_conn_read_all.3http.html">nng_http_conn_read_all(3http)</a>, +<a href="nng_http_conn_write_req.3http.html">nng_http_conn_write_req(3http)</a>, +<a href="nng_http_res_get_data.3http.html">nng_http_res_get_data(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_conn_write.3http.html b/man/v1.7.2/nng_http_conn_write.3http.html new file mode 100644 index 00000000..ce04e4ad --- /dev/null +++ b/man/v1.7.2/nng_http_conn_write.3http.html @@ -0,0 +1,166 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_conn_write(3http) +--- +<h1>nng_http_conn_write(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_conn_write - write to HTTP connection</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_conn_write</span><span class="tok-p">(</span><span class="tok-n">nng_http_conn</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">conn</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_conn_write()</code> function starts an asynchronous write to the +HTTP connection <em>conn</em> from the scatter/gather vector located in the +asynchronous I/O structure <em>aio</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The <a href="nng_aio_set_iov.3.html"><code>nng_aio_set_iov()</code></a> function must have been +called first, to set the scatter/gather vector for <em>aio</em>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>This function returns immediately, with no return value. +Completion of the operation is signaled via the <em>aio</em>, and the final +result may be obtained via <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>. +That result will either be zero or an error code.</p> +</div> +<div class="paragraph"> +<p>The I/O operation completes as soon as at least one byte has been +written, or an error has occurred. +Therefore, the number of bytes written may be less than requested. +The actual number of bytes written can be determined with +<a href="nng_aio_count.3.html"><code>nng_aio_count()</code></a>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This function is intended to facilitate uses cases that involve changing +the protocol from HTTP, such as WebSocket. +Most applications will never need to use this function. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The peer closed the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The <em>aio</em> does not contain a valid scatter/gather vector.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP operations are not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Timeout waiting for data from the connection.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_count.3.html">nng_aio_count(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio_set_iov.3.html">nng_aio_set_iov(3)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_conn_write_all.3http.html">nng_http_conn_write_all(3http)</a>, +<a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_conn_write_all.3http.html b/man/v1.7.2/nng_http_conn_write_all.3http.html new file mode 100644 index 00000000..567e6a0e --- /dev/null +++ b/man/v1.7.2/nng_http_conn_write_all.3http.html @@ -0,0 +1,207 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_conn_write_all(3http) +--- +<h1>nng_http_conn_write_all(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_conn_write_all - write all to HTTP connection</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_conn_write_all</span><span class="tok-p">(</span><span class="tok-n">nng_http_conn</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">conn</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_conn_write_all()</code> function starts an asynchronous write to the +HTTP connection <em>conn</em>, into the scatter/gather vector located in the +asynchronous I/O structure <em>aio</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The <a href="nng_aio_set_iov.3.html"><code>nng_aio_set_iov()</code></a> function must have been +called first, to set the scatter/gather vector for <em>aio</em>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>This function returns immediately, with no return value. +Completion of the operation is signaled via the <em>aio</em>, and the +final result may be obtained via <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>. +That result will either be zero or an error code.</p> +</div> +<div class="paragraph"> +<p>The I/O operation completes only when the entire amount of data +requested has been written, or an error has occurred. +If the operation completes successfully, then the entire requested data has +been written.</p> +</div> +<div class="paragraph"> +<p>It is still possible for a partial write to complete in the event of an error. +The actual number of bytes written can be determined with +<a href="nng_aio_count.3.html"><code>nng_aio_count()</code></a>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The main purpose for this function is to facilitate writing HTTP +body content. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Usually an HTTP request or response will have been written immediately +prior to this with <a href="nng_http_conn_write_req.3http.html"><code>http_conn_write_req()</code></a> or +<a href="nng_http_conn_write_res.3http.html"><code>http_conn_write_res()</code></a>. +In that case the request or response should have also contained +an <code>Content-Length</code> header, and possibly a <code>Content-Type</code> header. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +An easier solution to sending HTTP content data, is to include the +content with the request or reply using a function like +<a href="nng_http_req_copy_data.3http.html"><code>nng_http_req_copy_data()</code></a>. +In that case, the body data will be written automatically by the +<a href="nng_http_conn_write_req.3http.html"><code>http_conn_write_req()</code></a> or +<a href="nng_http_conn_write_req.3http.html"><code>http_conn_write_res()</code></a> function. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The peer closed the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The <em>aio</em> does not contain a valid scatter/gather vector.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP operations are not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Timeout waiting for data from the connection.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_count.3.html">nng_aio_count(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio_set_iov.3.html">nng_aio_set_iov(3)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_conn_write.3http.html">nng_http_conn_write(3http)</a>, +<a href="nng_http_conn_write_req.3http.html">http_conn_write_req(3http)</a>, +<a href="nng_http_conn_write_res.3http.html">http_conn_write_res(3http)</a>, +<a href="nng_http_req_copy_data.3http.html">nng_http_req_copy_data(3http)</a>, +<a href="nng_http_req_set_data.3http.html">nng_http_req_set_data(3http)</a>, +<a href="nng_http_res_copy_data.3http.html">nng_http_res_copy_data(3http)</a>, +<a href="nng_http_res_set_data.3http.html">nng_http_res_set_data(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_conn_write_req.3http.html b/man/v1.7.2/nng_http_conn_write_req.3http.html new file mode 100644 index 00000000..be6eec53 --- /dev/null +++ b/man/v1.7.2/nng_http_conn_write_req.3http.html @@ -0,0 +1,144 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_conn_write_req(3http) +--- +<h1>nng_http_conn_write_req(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_conn_write_req - write HTTP request</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_conn_write_req</span><span class="tok-p">(</span><span class="tok-n">nng_http_conn</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">conn</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_conn_write_req()</code> function starts an asynchronous write of +the HTTP request <em>req</em> to the connection <em>conn</em>. +The entire request is sent, +including headers, and if present, the request body data. +(The request body can be set with +<a href="nng_http_req_set_data.3http.html"><code>nng_http_req_set_data()</code></a> or +<a href="nng_http_req_copy_data.3http.html"><code>nng_http_req_copy_data()</code></a>.)</p> +</div> +<div class="paragraph"> +<p>This function returns immediately, with no return value. +Completion of the operation is signaled via the <em>aio</em>, and the final result +may be obtained via <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>. +That result will either be zero or an error code.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Consider using the +<a href="nng_http_client_transact.3http.html"><code>nng_http_client_transact()</code></a> or +<a href="nng_http_conn_transact.3http.html"><code>nng_http_conn_transact()</code></a> functions, +which provide a simpler interface for performing a complete HTTP client +transaction. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The peer closed the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP operations are not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Timeout waiting for data from the connection.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_client_transact.3http.html">nng_http_client_transact(3http)</a>, +<a href="nng_http_conn_read_all.3http.html">nng_http_conn_read_all(3http)</a>, +<a href="nng_http_conn_transact.3http.html">nng_http_conn_transact(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_conn_write_res.3http.html b/man/v1.7.2/nng_http_conn_write_res.3http.html new file mode 100644 index 00000000..8b39ddf8 --- /dev/null +++ b/man/v1.7.2/nng_http_conn_write_res.3http.html @@ -0,0 +1,156 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_conn_write_res(3http) +--- +<h1>nng_http_conn_write_res(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_conn_write_res - write HTTP response</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_conn_write_res</span><span class="tok-p">(</span><span class="tok-n">nng_http_conn</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">conn</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_conn_write_res()</code> function starts an asynchronous write of +the HTTP response <em>res</em> to the connection <em>conn</em>. +The entire response is sent, +including headers, and if present, the response body data. +(The response body can be set with +<a href="nng_http_res_set_data.3http.html"><code>nng_http_res_set_data()</code></a> or +<a href="nng_http_res_copy_data.3http.html"><code>nng_http_res_copy_data()</code></a>.)</p> +</div> +<div class="paragraph"> +<p>This function returns immediately, with no return value. +Completion of the operation is signaled via the <em>aio</em>, and the final result +may be obtained via <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>. +That result will either be zero or an error code.</p> +</div> +<div class="sect2"> +<h3 id="_persistent_connections">Persistent Connections</h3> +<div class="paragraph"> +<p>By default, for <code>HTTP/1.1</code> connections, the connection is kept open, and +will be reused to receive new requests.</p> +</div> +<div class="paragraph"> +<p>If however the <em>res</em> contains a header of <code>Connection:</code> with a value +of <code>Close</code> (case-insensitive) or the response corresponds to <code>HTTP/1.0</code>, +then the connection is immediately after sending the response.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Consider using the +<a href="nng_http_client_transact.3http.html"><code>nng_http_client_transact()</code></a> or +<a href="nng_http_conn_transact.3http.html"><code>nng_http_conn_transact()</code></a> functions, +which provide a simpler interface for performing a complete HTTP client +transaction. +</td> +</tr> +</table> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The peer closed the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP operations are not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Timeout waiting for data from the connection.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_http_client_connect.3http.html">nng_http_client_connect(3http)</a>, +<a href="nng_http_client_transact.3http.html">nng_http_client_transact(3http)</a>, +<a href="nng_http_conn_read_all.3http.html">nng_http_conn_read_all(3http)</a>, +<a href="nng_http_conn_transact.3http.html">nng_http_conn_transact(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_handler_alloc.3http.html b/man/v1.7.2/nng_http_handler_alloc.3http.html new file mode 100644 index 00000000..debed285 --- /dev/null +++ b/man/v1.7.2/nng_http_handler_alloc.3http.html @@ -0,0 +1,296 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_handler_alloc(3http) +--- +<h1>nng_http_handler_alloc(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_handler_alloc - allocate HTTP server handler</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_http_handler</span><span class="tok-w"> </span><span class="tok-n">nng_http_handler</span><span class="tok-p">;</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_handler_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">hp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-o">*</span><span class="tok-n">func</span><span class="tok-p">)(</span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_handler_alloc_directory</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">hp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">dirname</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_handler_alloc_file</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">hp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">filename</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_handler_alloc_redirect</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">hp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">status</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">location</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_handler_alloc_static</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">hp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">data</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">content_type</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_handler_alloc()</code> family of functions allocate a handler +which will be used to process requests coming into an HTTP server. +On success, a pointer to the handler is stored at the located pointed to +by <em>hp</em>.</p> +</div> +<div class="paragraph"> +<p>Every handler has a Request-URI to which it refers, which is determined +by the <em>path</em> argument. +Only the path component of the Request URI is +considered when determining whether the handler should be called.</p> +</div> +<div class="paragraph"> +<p>Additionally each handler has a method it is registered to handle +(the default is <code>GET</code>, see +<a href="nng_http_handler_set_method.3http.html"><code>nng_http_handler_set_method()</code></a>), and +optionally a 'Host' header it can be matched against (see +<a href="nng_http_handler_set_host.3http.html"><code>nng_http_handler_set_host()</code></a>).</p> +</div> +<div class="paragraph"> +<p>In some cases, a handler may reference a logical tree rather (directory) +rather than just a single element. +(See <a href="nng_http_handler_set_tree.3http.html"><code>nng_http_handler_set_tree()</code></a>).</p> +</div> +<div class="sect2"> +<h3 id="_custom_handler">Custom Handler</h3> +<div class="paragraph"> +<p>The generic (first) form of this creates a handler that uses a user-supplied +function to process HTTP requests. +This function uses the asynchronous I/O framework. +The function takes a pointer to an <a href="nng_aio.5.html"><code>nng_aio</code></a> structure.</p> +</div> +<div class="paragraph"> +<p>The <em>aio</em> will be passed with the following input values (retrieved with +<a href="nng_aio_get_input.3.html"><code>nng_aio_get_input()</code></a>):</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1">0: <code>nng_http_req *</code> <em>request</em></dt> +<dd> +<p>The client’s HTTP request.</p> +</dd> +<dt class="hdlist1">1: <code>nng_http_handler *</code> <em>handler</em></dt> +<dd> +<p>Pointer to the handler object.</p> +</dd> +<dt class="hdlist1">2: <code>nng_http_conn *</code> <em>conn</em></dt> +<dd> +<p>The underlying HTTP connection.</p> +</dd> +</dl> +</div> +<div class="paragraph"> +<p>The handler should create an <code>nng_http_res *</code> response (such as via +<a href="nng_http_res_alloc.3http.html"><code>nng_http_res_alloc()</code></a> or +<a href="nng_http_res_alloc_error.3http.html"><code>nng_http_res_alloc_error()</code></a>) and store that +in as the first output (index 0) with +<a href="nng_aio_set_output.3.html"><code>nng_aio_set_output()</code></a>.</p> +</div> +<div class="paragraph"> +<p>Alternatively, the handler may send the HTTP response (and any associated +body data) itself using the connection. +In that case the output at index 0 of the <em>aio</em> should be NULL.</p> +</div> +<div class="paragraph"> +<p>Finally, using the <a href="nng_aio_finish.3.html"><code>nng_aio_finish()</code></a> function, the +<em>aio</em> should be completed successfully. +If any non-zero status is returned back to the caller instead, +then a generic 500 response will be created and +sent, if possible, and the connection will be closed.</p> +</div> +<div class="paragraph"> +<p>The <em>aio</em> may be scheduled for deferred completion using the +<a href="nng_aio_defer.3.html"><code>nng_aio_defer()</code></a> function.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The callback function should <strong>NOT</strong> call +<a href="nng_aio_begin.3.html"><code>nng_aio_begin()</code></a>, +as that will already have been done by the server framework. +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_directory_handler">Directory Handler</h3> +<div class="paragraph"> +<p>The second member of this family, <code>nng_http_handler_alloc_directory()</code>, creates +a handler configured to serve a directory tree. +The <em>uri</em> is taken as the root, and files are served from the directory +tree rooted at <em>path</em>.</p> +</div> +<div class="paragraph"> +<p>When the client Request-URI resolves to a directory in the file system, +the handler looks first for a file named <code>index.html</code> or <code>index.htm</code>. +If one is found, then that file is returned back to the client. +If no such index file exists, then an <code>NNG_HTTP_STATUS_NOT_FOUND</code> (404) error is +sent back to the client.</p> +</div> +<div class="paragraph"> +<p>The <code>Content-Type</code> will be set automatically based upon the extension +of the requested file name. If a content type cannot be determined from +the extension, then <code>application/octet-stream</code> is used.</p> +</div> +<div class="paragraph"> +<p>The directory handler is created as a tree handler initially in exclusive mode (see +<a href="nng_http_handler_set_tree.3http.html">nng_http_handler_set_tree_exclusive</a>). +This can be changed by calling +<a href="nng_http_handler_set_tree.3http.html">nng_http_handler_set_tree(3http)</a> +after creating the directory handler.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_file_handler">File Handler</h3> +<div class="paragraph"> +<p>The third member of this family, <code>nng_http_handler_alloc_file()</code>, creates +a handler to serve up a single file; it does not traverse directories +or search for <code>index.html</code> or <code>index.htm</code> files.</p> +</div> +<div class="paragraph"> +<p>The <code>Content-Type</code> will be set automatically based upon the extension +of the requested file name. +If a content type cannot be determined from +the extension, then <code>application/octet-stream</code> is used.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_redirect_handler">Redirect Handler</h3> +<div class="paragraph"> +<p>The fourth member is used to arrange for a server redirect from one +URL to another. +The reply will be with status code <em>status</em>, which should be a 3XX +code such as 301, and a <code>Location:</code> header will contain the URL +referenced by <em>location</em>, with any residual suffix from the request +URI appended.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Use <a href="nng_http_handler_set_tree.3http.html"><code>nng_http_handler_set_tree()</code></a> +to redirect an entire tree. +For example, it is possible to redirect an entire HTTP site to another +HTTPS site by specifying <code>/</code> as the path and then using the base +of the new site, such as <code><a href="https://newsite.example.com" class="bare">https://newsite.example.com</a></code> as the +new location. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Be sure to use the appropriate value for <em>status</em>. +Permanent redirection should use 301 and temporary redirections should use 307. +In REST APIs, using a redirection to supply the new location of an object +created with <code>POST</code> should use 303. +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_static_handler">Static Handler</h3> +<div class="paragraph"> +<p>The fifth member of this family, <code>nng_http_handler_alloc_static()</code>, creates +a handler to serve up fixed content located in program data. +The client is +sent the <em>data</em>, with <code>Content-Length</code> of <em>size</em> bytes, and <code>Content-Type</code> of +<em>content_type</em>.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>path</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists to allocate a message.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_defer.3.html">nng_aio_defer(3)</a>, +<a href="nng_aio_finish.3.html">nng_aio_finish(3)</a>, +<a href="nng_aio_get_input.3.html">nng_aio_get_input(3)</a>, +<a href="nng_aio_set_output.3.html">nng_aio_set_output(3)</a>, +<a href="nng_http_handler_collect_body.3http.html">nng_http_handler_collect_body(3http)</a>, +<a href="nng_http_handler_free.3http.html">nng_http_handler_free(3http)</a>, +<a href="nng_http_handler_set_host.3http.html">nng_http_handler_set_host(3http)</a>, +<a href="nng_http_handler_set_method.3http.html">nng_http_handler_set_method(3http)</a>, +<a href="nng_http_handler_set_tree.3http.html">nng_http_handler_set_tree(3http)</a>, +<a href="nng_http_handler_set_tree.3http.html">nng_http_handler_set_tree_exclusive(3http)</a>, +<a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_alloc_error.3http.html">nng_http_res_alloc_error(3http)</a>, +<a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_handler_collect_body.3http.html b/man/v1.7.2/nng_http_handler_collect_body.3http.html new file mode 100644 index 00000000..4abb7889 --- /dev/null +++ b/man/v1.7.2/nng_http_handler_collect_body.3http.html @@ -0,0 +1,138 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_handler_collect_body(3http) +--- +<h1>nng_http_handler_collect_body(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_handler_collect_body - set HTTP handler to collect request body</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_handler_collect_body</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">handler</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">want</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">maxsz</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_handler_collect_body()</code> function causes the <em>handler</em> to +collect any request body that was submitted with the request, and attach +it to the <code>nng_http_req</code> before the handler is called.</p> +</div> +<div class="paragraph"> +<p>Subsequently the data can be retrieved by the handler from the request with the +<a href="nng_http_req_get_data.3http.html"><code>nng_http_req_get_data()</code></a> function.</p> +</div> +<div class="paragraph"> +<p>The collection is enabled if <em>want</em> is true. +Furthermore, the data that the client may sent is limited by the +value of <em>maxsz</em>. +If the client attempts to send more data than <em>maxsz</em>, then the +request will be terminated with a 400 <code>Bad Request</code> status.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Limiting the size of incoming request data can provide protection +against denial of service attacks, as a buffer of the client-supplied +size must be allocated to receive the data. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>In order to provide an unlimited size, use <code>(size_t)-1</code> for <em>maxsz</em>. +The value <code>0</code> for <em>maxsz</em> can be used to prevent any data from being passed +by the client.</p> +</div> +<div class="paragraph"> +<p>The built-in handlers for files, directories, and static data limit the +<em>maxsz</em> to zero by default. +Otherwise the default setting is to enable this capability with a default +value of <em>maxsz</em> of 1 megabyte.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The handler looks for data indicated by the <code>Content-Length:</code> HTTP +header. +If this header is absent, the request is assumed not to contain any data. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This specifically does not support the <code>Chunked</code> transfer-encoding. +This is considered a bug, and is a deficiency for full HTTP/1.1 compliance. +However, few clients send data in this format, so in practice this should +create few limitations. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a>, +<a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler(3http)</a>, +<a href="nng_http_req_get_data.3http.html">nng_http_req_get_data(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_handler_free.3http.html b/man/v1.7.2/nng_http_handler_free.3http.html new file mode 100644 index 00000000..69824498 --- /dev/null +++ b/man/v1.7.2/nng_http_handler_free.3http.html @@ -0,0 +1,75 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_handler_free(3http) +--- +<h1>nng_http_handler_free(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_handler_free - free HTTP server handler</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_handler_free</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">h</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_handler_free()</code> function frees an allocated HTTP server handler.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +It is an error to free a handler that is registered with a server. +Any handlers that are registered with servers are automatically freed +when the server itself is deallocated. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a>, +<a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_handler_get_data.3http.html b/man/v1.7.2/nng_http_handler_get_data.3http.html new file mode 100644 index 00000000..a4c2f4df --- /dev/null +++ b/man/v1.7.2/nng_http_handler_get_data.3http.html @@ -0,0 +1,64 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_handler_get_data(3http) +--- +<h1>nng_http_handler_get_data(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_handler_get_data - return extra data for HTTP handler</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_http_handler_get_data</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">handler</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_handler_get_data()</code> function returns the data previously +stored on <em>handler</em> using the function +<a href="nng_http_handler_set_data.3http.html"><code>nng_http_handler_set_data()</code></a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a>, +<a href="nng_http_handler_set_data.3http.html">nng_http_server_set_data(3http)</a>, +<a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_handler_set_data.3http.html b/man/v1.7.2/nng_http_handler_set_data.3http.html new file mode 100644 index 00000000..8e2a1bba --- /dev/null +++ b/man/v1.7.2/nng_http_handler_set_data.3http.html @@ -0,0 +1,89 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_handler_set_data(3http) +--- +<h1>nng_http_handler_set_data(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_handler_set_data - set extra data for HTTP handler</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_handler_set_data</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">handler</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">data</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-o">*</span><span class="tok-n">dtor</span><span class="tok-p">)(</span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-p">));</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_handler_set_data()</code> function is used to set an additional +<em>data</em> for the <em>handler</em>. +The stored <em>data</em> can be retrieved later in the handler function using +<a href="nng_http_handler_get_data.3http.html"><code>nng_http_handler_get_data()</code></a>.</p> +</div> +<div class="paragraph"> +<p>Additionally, when the handler is deallocated, if <em>dtor</em> is not <code>NULL</code>, +then it will be called with <em>data</em> as its argument. +The intended use of +this function is deallocate any resources associated with <em>data</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a>, +<a href="nng_http_handler_get_data.3http.html">nng_http_server_get_data(3http)</a>, +<a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_handler_set_host.3http.html b/man/v1.7.2/nng_http_handler_set_host.3http.html new file mode 100644 index 00000000..5e2479e5 --- /dev/null +++ b/man/v1.7.2/nng_http_handler_set_host.3http.html @@ -0,0 +1,113 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_handler_set_host(3http) +--- +<h1>nng_http_handler_set_host(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_handler_set_host - set host for HTTP handler</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_handler_set_host</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">handler</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">host</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_handler_set_host()</code> function is used to limit the scope of the +<em>handler</em> so that it will only be called when the specified <em>host</em> matches +the value of the <code>Host:</code> HTTP header.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This can be used to create servers with multiple handlers for virtual +hosting. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The value of the <em>host</em> can include a colon and port, and should match +exactly the value of the <code>Host</code> header sent by the client. +(Canonicalization of the host name is performed though.)</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +As the server framework does not support listening on multiple +ports, the port number can be elided. +The matching test only considers +the hostname or IP address, and ignores any trailing port number. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a>, +<a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_handler_set_method.3http.html b/man/v1.7.2/nng_http_handler_set_method.3http.html new file mode 100644 index 00000000..df39675e --- /dev/null +++ b/man/v1.7.2/nng_http_handler_set_method.3http.html @@ -0,0 +1,115 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_handler_set_method(3http) +--- +<h1>nng_http_handler_set_method(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_handler_set_method - set HTTP handler method</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_handler_set_method</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">handler</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">method</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_handler_set_method()</code> function sets the <em>method</em> that the +<em>handler</em> will be called for, such as "GET" or "POST". +(By default the "GET" method is handled.) +If <em>method</em> is <code>NULL</code>, then the request method +is not examined, and the handler will be executed regardless of the +method.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The server will automatically call "GET" handlers if the client +sends a "HEAD" request, and will suppress HTTP body data in the responses +sent for such requests. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +No validation of the <em>method</em> is performed, but HTTP specifications +insist that the actual method sent over the wire be capitalized. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The handler may always examine the actual method used using the +<a href="nng_http_req_get_method.3http.html"><code>nng_http_req_get_method()</code></a> function.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a>, +<a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler(3http)</a>, +<a href="nng_http_req_get_method.3http.html">nng_http_req_get_method(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_handler_set_tree.3http.html b/man/v1.7.2/nng_http_handler_set_tree.3http.html new file mode 100644 index 00000000..c7bf9ba1 --- /dev/null +++ b/man/v1.7.2/nng_http_handler_set_tree.3http.html @@ -0,0 +1,122 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_handler_set_tree(3http) +--- +<h1>nng_http_handler_set_tree(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_handler_set_tree - set HTTP handler to match trees</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_handler_set_tree</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">handler</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_handler_set_tree_exclusive</span><span class="tok-p">(</span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">handler</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_handler_set_tree()</code> function causes the <em>handler</em> to be matched if the request URI sent +by the client is a logical child of the path for <em>handler</em>, and no more specific +<em>handler</em> has been registered.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_http_handler_set_tree_exclusive()</code> function is similar to <code>nng_http_server_set_tree()</code> +with the distinction that the <em>handler</em> will be considered to <strong>exclusively</strong> handle its request URI. +Unlike <code>nng_http_server_set_tree()</code>, it will not be possible to register additional +handlers in logical subdirectories of <em>handler</em>.</p> +</div> +<div class="paragraph"> +<p>This is useful in cases when the handler would like to examine the entire path +and possibly behave differently; for example a REST API that uses the rest of +the path to pass additional parameters.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +These methods are useful when constructing API handlers where a single +service address (path) supports dynamically generated children. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The non-exclusive form is also useful for providing a default handler to be +generated when a more specific child does not exist. +This can provide a better experience for users than the standard 404 error +handling. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a>, +<a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler(3http)</a>, +<a href="nng_http_req_get_method.3http.html">nng_http_req_get_method(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_hijack.3http.html b/man/v1.7.2/nng_http_hijack.3http.html new file mode 100644 index 00000000..71db81f2 --- /dev/null +++ b/man/v1.7.2/nng_http_hijack.3http.html @@ -0,0 +1,128 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_hijack(3http) +--- +<h1>nng_http_hijack(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_hijack - hijack HTTP server connection</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_hijack</span><span class="tok-p">(</span><span class="tok-n">nng_http_conn</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">conn</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <code>nng_http_hijack()</code> function hijacks the connection <em>conn</em>, causing it +to be disassociated from the HTTP server where it was created.</p> +</div> +<div class="paragraph"> +<p>The purpose of this function is the creation of HTTP upgraders (such as +WebSocket), where the underlying HTTP connection will be taken over for +some other purpose, and should not be used any further by the server.</p> +</div> +<div class="paragraph"> +<p>This function is most useful when called from a handler function. +(See <a href="nng_http_handler_alloc.3http.html"><code>nng_http_handler_alloc()</code></a>.)</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +It is the responsibility of the caller to dispose of the underlying +connection when it is no longer needed. +Furthermore, the HTTP server will no longer send any responses to the +hijacked connection, so the caller should do that as well if appropriate. +(See <a href="nng_http_conn_write_res.3http.html"><code>nng_http_conn_write_res()</code></a>.) +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This function is intended to facilitate uses cases that involve changing +the protocol from HTTP, such as WebSocket. +Most applications will never need to use this function. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_http_conn_write_res.3http.html">nng_http_conn_write_res(3http)</a>, +<a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_add_header.3http.html b/man/v1.7.2/nng_http_req_add_header.3http.html new file mode 100644 index 00000000..80256572 --- /dev/null +++ b/man/v1.7.2/nng_http_req_add_header.3http.html @@ -0,0 +1,121 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_add_header(3http) +--- +<h1>nng_http_req_add_header(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_add_header - add HTTP request header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_req_add_header</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">key</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_add_header()</code> adds an HTTP header for the request +<em>req</em> and the <em>key</em> to the <em>val</em>. The <em>key</em> and <em>val</em> are copied.</p> +</div> +<div class="paragraph"> +<p>If a header with the value of <em>key</em> already exists, then a comma +and whitespace separate are appended to it, followed by <em>val</em>.</p> +</div> +<div class="paragraph"> +<p>If no such header already exists, then one is created with the value <em>val</em>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The HTTP specification requires that duplicate headers be treated +identically to a single header with multiple comma-delimited values. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +See <a href="nng_http_req_set_header.3http.html"><code>nng_http_req_set_header()</code></a> if +replacement of an existing header rather than appending to it is desired. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The value of <em>key</em> is case insensitive, and should not include the final +colon in an HTTP header. +For example, specifying <code>Host</code> or <code>hOSt</code> are +equivalent, whereas the value <code>Host:</code> is not a legal header key.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_del_header.3http.html">nng_http_req_del_header(3http)</a>, +<a href="nng_http_req_get_header.3http.html">nng_http_req_get_header(3http)</a>, +<a href="nng_http_req_set_header.3http.html">nng_http_req_set_header(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_alloc.3http.html b/man/v1.7.2/nng_http_req_alloc.3http.html new file mode 100644 index 00000000..34538861 --- /dev/null +++ b/man/v1.7.2/nng_http_req_alloc.3http.html @@ -0,0 +1,111 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_alloc(3http) +--- +<h1>nng_http_req_alloc(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_alloc - allocate HTTP request structure</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_req_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">reqp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-n">nng_url</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_alloc()</code> function allocates a new HTTP request structure +and stores a pointer to it in <em>reqp</em>. +The request will be initialized +to perform an HTTP/1.1 <code>GET</code> operation using the URL specified in <em>url</em>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It is possible to specify <code>NULL</code> for the URL. +In this case the URI for the request must be specified by a subsequent call +to <a href="nng_http_req_set_uri.3http.html"><code>nng_http_req_set_uri()</code></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists to allocate a message.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP support not configured.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_conn_read_req.3http.html">nng_http_conn_read_req(3http)</a>, +<a href="nng_http_conn_write_req.3http.html">nng_http_conn_write_req(3http)</a>, +<a href="nng_http_req_add_header.3http.html">nng_http_req_add_header(3http)</a>, +<a href="nng_http_req_copy_data.3http.html">nng_http_req_copy_data(3http)</a>, +<a href="nng_http_req_del_header.3http.html">nng_http_req_del_header(3http)</a>, +<a href="nng_http_req_free.3http.html">nng_http_req_free(3http)</a>, +<a href="nng_http_req_get_header.3http.html">nng_http_req_get_header(3http)</a>, +<a href="nng_http_req_get_method.3http.html">nng_http_req_get_method(3http)</a>, +<a href="nng_http_req_get_uri.3http.html">nng_http_req_get_uri(3http)</a>, +<a href="nng_http_req_get_version.3http.html">nng_http_req_get_version(3http)</a>, +<a href="nng_http_req_reset.3http.html">nng_http_req_reset(3http)</a>, +<a href="nng_http_req_set_data.3http.html">nng_http_req_set_data(3http)</a>, +<a href="nng_http_req_set_method.3http.html">nng_http_req_set_method(3http)</a>, +<a href="nng_http_req_set_uri.3http.html">nng_http_req_set_uri(3http)</a>, +<a href="nng_http_req_set_version.3http.html">nng_http_req_set_version(3http)</a>, +<a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_url_parse.3.html">nng_url_parse(3)</a> +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_copy_data.3http.html b/man/v1.7.2/nng_http_req_copy_data.3http.html new file mode 100644 index 00000000..d30d2f33 --- /dev/null +++ b/man/v1.7.2/nng_http_req_copy_data.3http.html @@ -0,0 +1,127 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_copy_data(3http) +--- +<h1>nng_http_req_copy_data(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_copy_data - copy HTTP request body</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_req_copy_data</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">body</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_copy_data()</code> makes a copy of <em>body</em> (of size <em>size</em>) +and sets the HTTP body for the request <em>req</em> to it. +The copy will be deallocated automatically when <em>req</em> is freed.</p> +</div> +<div class="paragraph"> +<p>The copied body data will be automatically sent with the request when it +is sent using <a href="nng_http_conn_write_req.3http.html"><code>nng_http_conn_write_req()</code></a>.</p> +</div> +<div class="paragraph"> +<p>This also updates the relevant <code>Content-Length</code> header of <em>req</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The current framework does not support sending data via chunked +transfer-encoding. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +To avoid copying data, the +<a href="nng_http_req_set_data.3http.html"><code>nng_http_req_set_data()</code></a> may be used instead. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It is a good idea to also set the <code>Content-Type</code> header. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_conn_write_req.3http.html">nng_http_conn_write_req(3http)</a>, +<a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_set_data.3http.html">nng_http_req_set_data(3http)</a>, +<a href="nng_http_req_set_header.3http.html">nng_http_req_set_header(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_del_header.3http.html b/man/v1.7.2/nng_http_req_del_header.3http.html new file mode 100644 index 00000000..9479f64b --- /dev/null +++ b/man/v1.7.2/nng_http_req_del_header.3http.html @@ -0,0 +1,87 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_del_header(3http) +--- +<h1>nng_http_req_del_header(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_del_header - delete HTTP request header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_req_del_header</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">key</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_del_header()</code> removes all HTTP headers with the +associated <em>key</em> from the request structure <em>req</em>.</p> +</div> +<div class="paragraph"> +<p>The value of <em>key</em> is case insensitive, and should not include the final +colon in an HTTP header. +For example, specifying <code>Host</code> or <code>hOSt</code> are +equivalent, whereas the value <code>Host:</code> is not a legal header key.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOENT</code> +</td> +<td class="hdlist2"> +<p>No header with the key <em>key</em> was present.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_add_header.3http.html">nng_http_req_add_header(3http)</a>, +<a href="nng_http_req_del_header.3http.html">nng_http_req_del_header(3http)</a>, +<a href="nng_http_req_get_header.3http.html">nng_http_req_get_header(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_free.3http.html b/man/v1.7.2/nng_http_req_free.3http.html new file mode 100644 index 00000000..bfea2c50 --- /dev/null +++ b/man/v1.7.2/nng_http_req_free.3http.html @@ -0,0 +1,75 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_free(3http) +--- +<h1>nng_http_req_free(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_free - free HTTP request structure</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_req_free</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_free()</code> function deallocates the HTTP request structure +<em>req</em> entirely.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Instead of freeing and reallocating request structures, it is possible +to reuse <em>req</em> with <a href="nng_http_req_reset.3http.html"><code>nng_http_req_reset()</code></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_reset.3http.html">nng_http_req_reset(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_get_data.3http.html b/man/v1.7.2/nng_http_req_get_data.3http.html new file mode 100644 index 00000000..e7c4dc0e --- /dev/null +++ b/man/v1.7.2/nng_http_req_get_data.3http.html @@ -0,0 +1,78 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_get_data(3http) +--- +<h1>nng_http_req_get_data(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_get_data - get HTTP request body</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_req_get_data</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">bodyp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sizep</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_get_data()</code> gets the HTTP body associated with +the request <em>req</em>, storing a pointer to the buffer at the location referenced +by <em>bodyp</em>, and the length of the associated buffer at the location referenced +by <em>sizep</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The buffer returned is owned by <em>req</em>, and will automatically freed +when the request is freed. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_set_data.3http.html">nng_http_req_copy_data(3http)</a>, +<a href="nng_http_req_copy_data.3http.html">nng_http_req_copy_data(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_get_header.3http.html b/man/v1.7.2/nng_http_req_get_header.3http.html new file mode 100644 index 00000000..e3e46a9a --- /dev/null +++ b/man/v1.7.2/nng_http_req_get_header.3http.html @@ -0,0 +1,70 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_get_header(3http) +--- +<h1>nng_http_req_get_header(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_get_header - return HTTP request header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_http_req_get_header</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">key</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_get_header()</code> looks for an HTTP header <em>key</em> in +the request <em>req</em>, and returns the associated value if found, +or <code>NULL</code> if not found.</p> +</div> +<div class="paragraph"> +<p>The value of <em>key</em> is case insensitive, and should not include the final +colon in an HTTP header. +For example, specifying <code>Host</code> or <code>hOSt</code> are +equivalent, whereas the value <code>Host:</code> will not find anything.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>HTTP header value for <em>key</em>, if it exists, or NULL otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_add_header.3http.html">nng_http_req_add_header(3http)</a>, +<a href="nng_http_req_set_header.3http.html">nng_http_req_set_header(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_get_method.3http.html b/man/v1.7.2/nng_http_req_get_method.3http.html new file mode 100644 index 00000000..703c7781 --- /dev/null +++ b/man/v1.7.2/nng_http_req_get_method.3http.html @@ -0,0 +1,63 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_get_method(3http) +--- +<h1>nng_http_req_get_method(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_get_method - return HTTP request method</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_http_req_get_method</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_get_method()</code> returns the HTTP method associated with +the request <em>req</em>. +The value will be a string, such as "GET" or "POST".</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Request method as a string.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_set_method.3http.html">nng_http_req_set_method(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_get_uri.3http.html b/man/v1.7.2/nng_http_req_get_uri.3http.html new file mode 100644 index 00000000..c2b70502 --- /dev/null +++ b/man/v1.7.2/nng_http_req_get_uri.3http.html @@ -0,0 +1,65 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_get_uri(3http) +--- +<h1>nng_http_req_get_uri(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_get_uri - return HTTP request URI</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_http_req_get_uri</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_get_uri()</code> returns the URI (path) associated with the HTTP +request <em>req</em>. +The value returned includes the path, as well as any query information or +fragment. The value will look like a file system path +with those optional components appended, such as <code>/api/get_info.cgi?name=garrett</code>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Request URI as a string.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_set_uri.3http.html">nng_http_req_set_uri(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_get_version.3http.html b/man/v1.7.2/nng_http_req_get_version.3http.html new file mode 100644 index 00000000..80d2a09c --- /dev/null +++ b/man/v1.7.2/nng_http_req_get_version.3http.html @@ -0,0 +1,62 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_get_version(3http) +--- +<h1>nng_http_req_get_version(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_get_version - return HTTP request protocol version</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_http_req_get_version</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_get_version()</code> returns a string representing the HTTP +protocol version associated with the request <em>req</em>, such as "HTTP/1.1".</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Request version as a string.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_set_version.3http.html">nng_http_req_set_version(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_reset.3http.html b/man/v1.7.2/nng_http_req_reset.3http.html new file mode 100644 index 00000000..d1ccd61b --- /dev/null +++ b/man/v1.7.2/nng_http_req_reset.3http.html @@ -0,0 +1,76 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_reset(3http) +--- +<h1>nng_http_req_reset(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_reset - reset HTTP request structure</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_req_reset</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_reset()</code> function resets the request <em>req</em> so that it +is just as if it had been freshly allocated with +<a href="nng_http_req_alloc.3http.html"><code>nng_http_req_alloc()</code></a> with a <code>NULL</code> URL.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Before using this with an HTTP operation, the URI must be set using +<a href="nng_http_req_set_uri.3http.html"><code>nng_http_req_set_uri()</code></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_set_uri.3http.html">nng_http_req_set_uri(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_set_data.3http.html b/man/v1.7.2/nng_http_req_set_data.3http.html new file mode 100644 index 00000000..9fcbb46f --- /dev/null +++ b/man/v1.7.2/nng_http_req_set_data.3http.html @@ -0,0 +1,129 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_set_data(3http) +--- +<h1>nng_http_req_set_data(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_set_data - set HTTP request body</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_req_set_data</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">body</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_set_data()</code> sets the HTTP body associated with +the request <em>req</em> to <em>body</em>, and the size of the body to <em>size</em>. +This body data will be automatically sent with the request when it +is sent using <a href="nng_http_conn_write_req.3http.html"><code>nng_http_conn_write_req()</code></a>.</p> +</div> +<div class="paragraph"> +<p>This also updates the relevant <code>Content-Length</code> header of <em>req</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The current framework does not support sending data via chunked +transfer-encoding. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>body</em> is <strong>not</strong> copied, and the caller must ensure that it is available +until the <em>req</em> is deallocated.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +To have a local copy allocated with <em>req</em> that will be automatically +deallocated when <em>req</em> is freed, +see <a href="nng_http_req_copy_data.3http.html"><code>nng_http_req_copy_data()</code></a>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It is a good idea to also set the <code>Content-Type</code> header. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_conn_write_req.3http.html">nng_http_conn_write_req(3http)</a>, +<a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_copy_data.3http.html">nng_http_req_copy_data(3http)</a>, +<a href="nng_http_req_set_header.3http.html">nng_http_req_set_header(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_set_header.3http.html b/man/v1.7.2/nng_http_req_set_header.3http.html new file mode 100644 index 00000000..5c4780f7 --- /dev/null +++ b/man/v1.7.2/nng_http_req_set_header.3http.html @@ -0,0 +1,103 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_set_header(3http) +--- +<h1>nng_http_req_set_header(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_set_header - set HTTP request header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_req_set_header</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">key</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_set_header()</code> sets the HTTP header for the request +<em>req</em> and the <em>key</em> to the <em>val</em>. +The <em>key</em> and <em>val</em> are copied. +Any previous header with the same <em>key</em> is replaced.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +See <a href="nng_http_req_add_header.3http.html"><code>nng_http_req_add_header()</code></a> to +add additional headers with the same <em>key</em> without replacing them. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The value of <em>key</em> is case insensitive, and should not include the final +colon in an HTTP header. +For example, specifying <code>Host</code> or <code>hOSt</code> are +equivalent, whereas the value <code>Host:</code> is not a legal header key.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_add_header.3http.html">nng_http_req_add_header(3http)</a>, +<a href="nng_http_req_del_header.3http.html">nng_http_req_del_header(3http)</a>, +<a href="nng_http_req_get_header.3http.html">nng_http_req_get_header(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_set_method.3http.html b/man/v1.7.2/nng_http_req_set_method.3http.html new file mode 100644 index 00000000..83ace774 --- /dev/null +++ b/man/v1.7.2/nng_http_req_set_method.3http.html @@ -0,0 +1,87 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_set_method(3http) +--- +<h1>nng_http_req_set_method(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_set_method - set HTTP request method</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_req_set_method</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">method</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_set_method()</code> sets the HTTP method associated with +the request <em>req</em> to <em>method</em>. The <em>method</em> must be a string, +such as "GET" or "POST", and the HTTP specifications indicate that it must +be upper case.</p> +</div> +<div class="paragraph"> +<p>The default value method for newly allocated requests is "GET".</p> +</div> +<div class="paragraph"> +<p>A local copy of the <em>method</em> is made in the request <em>req</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_get_method.3http.html">nng_http_req_get_method(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_set_uri.3http.html b/man/v1.7.2/nng_http_req_set_uri.3http.html new file mode 100644 index 00000000..2c1475bb --- /dev/null +++ b/man/v1.7.2/nng_http_req_set_uri.3http.html @@ -0,0 +1,113 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_set_uri(3http) +--- +<h1>nng_http_req_set_uri(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_set_uri - set HTTP request URI</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_req_set_uri</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">uri</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_set_uri()</code> sets the Request-URI associated with +the request <em>req</em> to <em>uri</em>. +The <em>uri</em> should contain precisely the +string that will be sent to the HTTP server in the request, including +any query information or fragment.</p> +</div> +<div class="paragraph"> +<p>A local copy of the <em>uri</em> is made in the request <em>req</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +No validation or canonicalization of the <em>uri</em> is performed. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The <a href="nng_url_parse.3.html"><code>nng_url_parse()</code></a> function can be used to +perform validation and canonicalization. +The <code>u_requri</code> member will +contain a suitable value that can be used with this function. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_get_uri.3http.html">nng_http_req_get_uri(3http)</a>, +<a href="nng_url_parse.3.html">nng_url_parse(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_req_set_version.3http.html b/man/v1.7.2/nng_http_req_set_version.3http.html new file mode 100644 index 00000000..e9de9116 --- /dev/null +++ b/man/v1.7.2/nng_http_req_set_version.3http.html @@ -0,0 +1,111 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_req_set_version(3http) +--- +<h1>nng_http_req_set_version(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_req_set_version - set HTTP request protocol version</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_req_set_version</span><span class="tok-p">(</span><span class="tok-n">nng_http_req</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">version</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_req_set_version()</code> sets the HTTP protocol version associated with +the request <em>req</em> to <em>version</em>. +The <em>version</em> must be a string containing +a valid HTTP protocol version, such as "HTTP/1.0". +The default value is "HTTP/1.1".</p> +</div> +<div class="paragraph"> +<p>A local copy of the <em>version</em> is made in the request <em>req</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +No validation of the version supplied is performed. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The library does not contain support for versions of HTTP other than +"HTTP/1.0" and "HTTP/1.1". +Specifying any other version may result in unspecified behavior. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_req_get_version.3http.html">nng_http_req_get_version(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_add_header.3http.html b/man/v1.7.2/nng_http_res_add_header.3http.html new file mode 100644 index 00000000..7a0b7d88 --- /dev/null +++ b/man/v1.7.2/nng_http_res_add_header.3http.html @@ -0,0 +1,121 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_add_header(3http) +--- +<h1>nng_http_res_add_header(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_add_header - add HTTP response header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_add_header</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">key</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_add_header()</code> adds an HTTP header for the response +<em>res</em> and the <em>key</em> to the <em>val</em>. +The <em>key</em> and <em>val</em> are copied.</p> +</div> +<div class="paragraph"> +<p>If a header with the value of <em>key</em> already exists, then a comma +and whitespace separate are appended to it, followed by <em>val</em>.</p> +</div> +<div class="paragraph"> +<p>If no such header already exists, then one is created with the value <em>val</em>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The HTTP specification requires that duplicate headers be treated +identically to a single header with multiple comma-delimited values. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +See <a href="nng_http_res_set_header.3http.html"><code>nng_http_res_set_header()</code></a> if +replacement of an existing header rather than appending to it is desired. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The value of <em>key</em> is case insensitive, and should not include the final +colon in an HTTP header. For example, specifying <code>Host</code> or <code>hOSt</code> are +equivalent, whereas the value <code>Host:</code> is not a legal header key.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_del_header.3http.html">nng_http_res_del_header(3http)</a>, +<a href="nng_http_res_get_header.3http.html">nng_http_res_get_header(3http)</a>, +<a href="nng_http_res_set_header.3http.html">nng_http_res_set_header(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_alloc.3http.html b/man/v1.7.2/nng_http_res_alloc.3http.html new file mode 100644 index 00000000..7eb1486b --- /dev/null +++ b/man/v1.7.2/nng_http_res_alloc.3http.html @@ -0,0 +1,111 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_alloc(3http) +--- +<h1>nng_http_res_alloc(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_alloc - allocate HTTP response structure</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">resp</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_alloc()</code> function allocates a new HTTP response structure +and stores a pointer to it in <em>resp</em>. +The response will be initialized +with status code 200 (<code>NNG_HTTP_STATUS_OK</code>), and a reason phrase of <code>OK</code>, +and HTTP protocol version <code>HTTP/1.1</code>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +When an error response is needed, consider using +<a href="nng_http_res_alloc_error.3http.html"><code>nng_http_res_alloc_error()</code></a> instead. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists to allocate a message.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP support not configured.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_conn_read_res.3http.html">nng_http_conn_read_res(3http)</a>, +<a href="nng_http_conn_write_res.3http.html">nng_http_conn_write_res(3http)</a>, +<a href="nng_http_req_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_res_alloc_error.3http.html">nng_http_res_alloc_error(3http)</a>, +<a href="nng_http_res_add_header.3http.html">nng_http_res_add_header(3http)</a>, +<a href="nng_http_res_copy_data.3http.html">nng_http_res_copy_data(3http)</a>, +<a href="nng_http_res_del_header.3http.html">nng_http_res_del_header(3http)</a>, +<a href="nng_http_res_free.3http.html">nng_http_res_free(3http)</a>, +<a href="nng_http_res_get_header.3http.html">nng_http_res_get_header(3http)</a>, +<a href="nng_http_res_get_reason.3http.html">nng_http_res_get_reason(3http)</a>, +<a href="nng_http_res_get_status.3http.html">nng_http_res_get_status(3http)</a>, +<a href="nng_http_res_get_version.3http.html">nng_http_res_get_version(3http)</a>, +<a href="nng_http_res_reset.3http.html">nng_http_res_reset(3http)</a>, +<a href="nng_http_res_set_data.3http.html">nng_http_res_set_data(3http)</a>, +<a href="nng_http_res_set_reason.3http.html">nng_http_res_set_reason(3http)</a>, +<a href="nng_http_res_set_status.3http.html">nng_http_res_set_status(3http)</a>, +<a href="nng_http_res_set_version.3http.html">nng_http_res_set_version(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_alloc_error.3http.html b/man/v1.7.2/nng_http_res_alloc_error.3http.html new file mode 100644 index 00000000..8c24fe9f --- /dev/null +++ b/man/v1.7.2/nng_http_res_alloc_error.3http.html @@ -0,0 +1,101 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_alloc_error(3http) +--- +<h1>nng_http_res_alloc_error(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_alloc_error - allocate HTTP error response</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_alloc_error</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">resp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">status</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_alloc_error()</code> function allocates a new HTTP response structure +and stores a pointer to it in <em>resp</em>. +The response will be initialized +with the status code <em>status</em>, a corresponding reason phrase, and +a simple HTML page containing the same information will be generated and +attached to the response. +(Relevant HTTP headers will be set as well, such as <code>Content-Type</code> +and <code>Content-Length</code>.) +The HTTP protocol version is also set to "HTTP/1.1".</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This is the simplest way to generate an error response. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists to allocate a message.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP support not configured.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_free.3http.html">nng_http_res_free(3http)</a>, +<a href="nng_http_res_set_reason.3http.html">nng_http_res_set_reason(3http)</a>, +<a href="nng_http_res_set_status.3http.html">nng_http_res_set_status(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_copy_data.3http.html b/man/v1.7.2/nng_http_res_copy_data.3http.html new file mode 100644 index 00000000..21c2d93c --- /dev/null +++ b/man/v1.7.2/nng_http_res_copy_data.3http.html @@ -0,0 +1,127 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_copy_data(3http) +--- +<h1>nng_http_res_copy_data(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_copy_data - copy HTTP response body</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_copy_data</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">body</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_copy_data()</code> makes a copy of <em>body</em> (of size <em>size</em>) +and sets the HTTP body for the response <em>res</em> to it. +The copy will be deallocated automatically when <em>res</em> is freed.</p> +</div> +<div class="paragraph"> +<p>The copied body data will be automatically sent with the response when it +is sent using <a href="nng_http_conn_write_res.3http.html"><code>nng_http_conn_write_res()</code></a>.</p> +</div> +<div class="paragraph"> +<p>This also updates the relevant <code>Content-Length</code> header of <em>res</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The current framework does not support sending data via chunked +transfer-encoding. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +To avoid copying data, the +<a href="nng_http_res_set_data.3http.html"><code>nng_http_res_set_data()</code></a> may be used instead. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It is a good idea to also set the <code>Content-Type</code> header. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_conn_write_res.3http.html">nng_http_conn_write_res(3http)</a>, +<a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_set_data.3http.html">nng_http_res_set_data(3http)</a>, +<a href="nng_http_res_set_header.3http.html">nng_http_res_set_header(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_del_header.3http.html b/man/v1.7.2/nng_http_res_del_header.3http.html new file mode 100644 index 00000000..c6fbbd3b --- /dev/null +++ b/man/v1.7.2/nng_http_res_del_header.3http.html @@ -0,0 +1,86 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_del_header(3http) +--- +<h1>nng_http_res_del_header(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_del_header - delete HTTP response header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_del_header</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">key</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_del_header()</code> removes all HTTP headers with the +associated <em>key</em> from the response structure <em>res</em>.</p> +</div> +<div class="paragraph"> +<p>The value of <em>key</em> is case insensitive, and should not include the final +colon in an HTTP header. For example, specifying <code>Host</code> or <code>hOSt</code> are +equivalent, whereas the value <code>Host:</code> is not a legal header key.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOENT</code> +</td> +<td class="hdlist2"> +<p>No header with the key <em>key</em> was present.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_add_header.3http.html">nng_http_res_add_header(3http)</a>, +<a href="nng_http_res_del_header.3http.html">nng_http_res_del_header(3http)</a>, +<a href="nng_http_res_get_header.3http.html">nng_http_res_get_header(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_free.3http.html b/man/v1.7.2/nng_http_res_free.3http.html new file mode 100644 index 00000000..77b05b3e --- /dev/null +++ b/man/v1.7.2/nng_http_res_free.3http.html @@ -0,0 +1,75 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_free(3http) +--- +<h1>nng_http_res_free(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_free - free HTTP response structure</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_free</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">req</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_free()</code> function deallocates the HTTP response structure +<em>res</em> entirely.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Instead of freeing and reallocating response structures, it is possible +to reuse <em>res</em> with <a href="nng_http_res_reset.3http.html"><code>nng_http_res_reset()</code></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_reset.3http.html">nng_http_res_reset(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_get_data.3http.html b/man/v1.7.2/nng_http_res_get_data.3http.html new file mode 100644 index 00000000..197491d4 --- /dev/null +++ b/man/v1.7.2/nng_http_res_get_data.3http.html @@ -0,0 +1,78 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_get_data(3http) +--- +<h1>nng_http_res_get_data(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_get_data - get HTTP response body</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_get_data</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">bodyp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sizep</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_get_data()</code> gets the HTTP body associated with +the request <em>res</em>, storing a pointer to the buffer at the location referenced +by <em>bodyp</em>, and the length of the associated buffer at the location referenced +by <em>sizep</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The buffer returned is owned by <em>res</em>, and will automatically freed +when the request is freed. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_req_alloc(3http)</a>, +<a href="nng_http_res_set_data.3http.html">nng_http_req_copy_data(3http)</a>, +<a href="nng_http_res_copy_data.3http.html">nng_http_req_copy_data(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_get_header.3http.html b/man/v1.7.2/nng_http_res_get_header.3http.html new file mode 100644 index 00000000..eb092296 --- /dev/null +++ b/man/v1.7.2/nng_http_res_get_header.3http.html @@ -0,0 +1,70 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_get_header(3http) +--- +<h1>nng_http_res_get_header(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_get_header - return HTTP response header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_http_res_get_header</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">key</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_get_header()</code> looks for an HTTP header <em>key</em> in +the response <em>res</em>, and returns the associated value if found, +or <code>NULL</code> if not found.</p> +</div> +<div class="paragraph"> +<p>The value of <em>key</em> is case insensitive, and should not include the final +colon in an HTTP header. +For example, specifying <code>Host</code> or <code>hOSt</code> are +equivalent, whereas the value <code>Host:</code> will not find anything.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>HTTP header value for <em>key</em>, if it exists, or NULL otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_add_header.3http.html">nng_http_res_add_header(3http)</a>, +<a href="nng_http_res_set_header.3http.html">nng_http_res_set_header(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_get_reason.3http.html b/man/v1.7.2/nng_http_res_get_reason.3http.html new file mode 100644 index 00000000..467011bd --- /dev/null +++ b/man/v1.7.2/nng_http_res_get_reason.3http.html @@ -0,0 +1,66 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_get_reason(3http) +--- +<h1>nng_http_res_get_reason(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_get_reason - return HTTP response reason</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_http_res_get_reason</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_get_reason()</code> returns a string representing the +reason associated with the response <em>res</em>. +This is a human-readable explanation of the status code that +would be obtained from +<a href="nng_http_res_get_status.3http.html"><code>nng_http_res_get_status()</code></a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Reason as a string.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_get_status.3http.html">nng_http_res_get_status(3http)</a>, +<a href="nng_http_res_set_reason.3http.html">nng_http_res_set_reason(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_get_status.3http.html b/man/v1.7.2/nng_http_res_get_status.3http.html new file mode 100644 index 00000000..a9ae532b --- /dev/null +++ b/man/v1.7.2/nng_http_res_get_status.3http.html @@ -0,0 +1,146 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_get_status(3http) +--- +<h1>nng_http_res_get_status(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_get_status - return HTTP status code</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_get_status</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_get_status()</code> returns a numeric code corresponding to +the HTTP status of the response <em>res</em>.</p> +</div> +<div class="paragraph"> +<p>For convenience, a number of predefined symbols corresponding to well-known +HTTP status codes are available.</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_CONTINUE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">100</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_SWITCHING</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">101</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PROCESSING</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">102</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_OK</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">200</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_CREATED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">201</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_ACCEPTED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">202</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NOT_AUTHORITATIVE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">203</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NO_CONTENT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">204</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_RESET_CONTENT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">205</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PARTIAL_CONTENT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">206</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_MULTI_STATUS</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">207</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_ALREADY_REPORTED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">208</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_IM_USED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">226</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_MULTIPLE_CHOICES</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">300</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_STATUS_MOVED_PERMANENTLY</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">301</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_FOUND</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">302</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_SEE_OTHER</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">303</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NOT_MODIFIED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">304</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_USE_PROXY</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">305</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_TEMPORARY_REDIRECT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">307</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PERMANENT_REDIRECT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">308</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_BAD_REQUEST</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">400</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_UNAUTHORIZED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">401</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PAYMENT_REQUIRED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">402</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_FORBIDDEN</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">403</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NOT_FOUND</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">404</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_METHOD_NOT_ALLOWED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">405</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NOT_ACCEPTABLE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">406</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">407</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_REQUEST_TIMEOUT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">408</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_CONFLICT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">409</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_GONE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">410</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_LENGTH_REQUIRED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">411</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PRECONDITION_FAILED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">412</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PAYLOAD_TOO_LARGE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">413</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_ENTITY_TOO_LONG</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">414</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">415</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">416</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_EXPECTATION_FAILED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">417</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_TEAPOT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">418</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">422</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_LOCKED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">423</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_FAILED_DEPENDENCY</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">424</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_UPGRADE_REQUIRED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">426</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PRECONDITION_REQUIRED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">428</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_TOO_MANY_REQUESTS</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">429</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_HEADERS_TOO_LARGE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">431</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">451</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">500</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NOT_IMPLEMENTED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">501</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_BAD_GATEWAY</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">502</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_SERVICE_UNAVAILABLE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">503</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_GATEWAY_TIMEOUT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">504</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">505</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">506</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_INSUFFICIENT_STORAGE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">507</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_LOOP_DETECTED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">508</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NOT_EXTENDED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">510</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">511</span><span class="tok-p">,</span> +<span class="tok-p">}</span></code></pre> +</div> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +When displaying status information to users (or logging such information), +consider also including the reason obtained with +<a href="nng_http_res_get_reason.3http.html"><code>nng_http_res_get_reason()</code></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>HTTP status code.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_get_reason.3http.html">nng_http_res_get_reason(3http)</a>, +<a href="nng_http_res_set_status.3http.html">nng_http_res_set_status(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_get_version.3http.html b/man/v1.7.2/nng_http_res_get_version.3http.html new file mode 100644 index 00000000..8e8e15fb --- /dev/null +++ b/man/v1.7.2/nng_http_res_get_version.3http.html @@ -0,0 +1,62 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_get_version(3http) +--- +<h1>nng_http_res_get_version(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_get_version - return HTTP response protocol version</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_http_res_get_version</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_get_version()</code> returns a string representing the HTTP +protocol version associated with the request <em>res</em>, such as "HTTP/1.1".</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Response version as a string.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_set_version.3http.html">nng_http_res_set_version(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_reset.3http.html b/man/v1.7.2/nng_http_res_reset.3http.html new file mode 100644 index 00000000..cded2a7b --- /dev/null +++ b/man/v1.7.2/nng_http_res_reset.3http.html @@ -0,0 +1,62 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_reset(3http) +--- +<h1>nng_http_res_reset(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_reset - reset HTTP response structure</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_reset</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_reset()</code> function resets the response <em>res</em> so that it +is just as if it had been freshly allocated with +<a href="nng_http_res_alloc.3http.html"><code>nng_http_res_alloc()</code></a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_set_data.3http.html b/man/v1.7.2/nng_http_res_set_data.3http.html new file mode 100644 index 00000000..fc392d09 --- /dev/null +++ b/man/v1.7.2/nng_http_res_set_data.3http.html @@ -0,0 +1,129 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_set_data(3http) +--- +<h1>nng_http_res_set_data(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_set_data - set HTTP response body</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_set_data</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">body</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_set_data()</code> sets the HTTP body associated with +the response <em>res</em> to <em>body</em>, and the size of the body to <em>size</em>. +This body data will be automatically sent with the response when it +is sent using <a href="nng_http_conn_write_res.3http.html"><code>nng_http_conn_write_res()</code></a>.</p> +</div> +<div class="paragraph"> +<p>This also updates the relevant <code>Content-Length</code> header of <em>res</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The current framework does not support sending data via chunked +transfer-encoding. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>body</em> is <strong>not</strong> copied, and the caller must ensure that it is available +until the <em>res</em> is deallocated.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +To have a local copy allocated with <em>res</em> that will be automatically +deallocated when <em>res</em> is freed, +see <a href="nng_http_res_copy_data.3http.html"><code>nng_http_res_copy_data()</code></a>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It is a good idea to also set the <code>Content-Type</code> header. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_conn_write_res.3http.html">nng_http_conn_write_res(3http)</a>, +<a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_copy_data.3http.html">nng_http_res_copy_data(3http)</a>, +<a href="nng_http_res_set_header.3http.html">nng_http_res_set_header(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_set_header.3http.html b/man/v1.7.2/nng_http_res_set_header.3http.html new file mode 100644 index 00000000..7961c7de --- /dev/null +++ b/man/v1.7.2/nng_http_res_set_header.3http.html @@ -0,0 +1,103 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_set_header(3http) +--- +<h1>nng_http_res_set_header(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_set_header - set HTTP response header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_set_header</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">key</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_set_header()</code> sets the HTTP header for the response +<em>res</em> and the <em>key</em> to the <em>val</em>. +The <em>key</em> and <em>val</em> are copied. +Any previous header with the same <em>key</em> is replaced.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +See <a href="nng_http_res_add_header.3http.html"><code>nng_http_res_add_header()</code></a> to +add additional headers with the same <em>key</em> without replacing them. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The value of <em>key</em> is case insensitive, and should not include the final +colon in an HTTP header. +For example, specifying <code>Host</code> or <code>hOSt</code> are +equivalent, whereas the value <code>Host:</code> is not a legal header key.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_add_header.3http.html">nng_http_res_add_header(3http)</a>, +<a href="nng_http_res_del_header.3http.html">nng_http_res_del_header(3http)</a>, +<a href="nng_http_res_get_header.3http.html">nng_http_res_get_header(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_set_reason.3http.html b/man/v1.7.2/nng_http_res_set_reason.3http.html new file mode 100644 index 00000000..d5902e0c --- /dev/null +++ b/man/v1.7.2/nng_http_res_set_reason.3http.html @@ -0,0 +1,101 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_set_reason(3http) +--- +<h1>nng_http_res_set_reason(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_set_reason - set HTTP response reason</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_set_reason</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">reason</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_set_reason()</code> sets the human readable reason +associated with the response <em>res</em> to <em>reason</em>.</p> +</div> +<div class="paragraph"> +<p>If the value of <em>reason</em> is <code>NULL</code> (the default), then a default reason +phrase is supplied based upon the value of the status code (see +<a href="nng_http_res_set_status.3http.html"><code>nng_http_res_set_status()</code></a>).</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The <em>reason</em> is never parsed automatically, but it can be a hint for humans + to help them understand the nature of any erroneous result. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>A local copy of the <em>reason</em> is made in the response <em>res</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_get_reason.3http.html">nng_http_req_get_reason(3http)</a>, +<a href="nng_http_res_set_status.3http.html">nng_http_req_set_status(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_set_status.3http.html b/man/v1.7.2/nng_http_res_set_status.3http.html new file mode 100644 index 00000000..3a702625 --- /dev/null +++ b/man/v1.7.2/nng_http_res_set_status.3http.html @@ -0,0 +1,163 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_set_status(3http) +--- +<h1>nng_http_res_set_status(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_set_status - set HTTP response status</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_set_status</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">status</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_set_status()</code> sets the numeric HTTP status code +associated with the response <em>res</em> to <em>status</em>. +The default value for a newly allocated response is 200 (<code>NNG_HTTP_STATUS_OK</code>).</p> +</div> +<div class="paragraph"> +<p>The <em>status</em> is not verified, so the caller should take care to ensure +that only a valid code is supplied.</p> +</div> +<div class="paragraph"> +<p>For convenience, a number of predefined symbols are available.</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_CONTINUE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">100</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_SWITCHING</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">101</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PROCESSING</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">102</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_OK</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">200</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_CREATED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">201</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_ACCEPTED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">202</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NOT_AUTHORITATIVE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">203</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NO_CONTENT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">204</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_RESET_CONTENT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">205</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PARTIAL_CONTENT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">206</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_MULTI_STATUS</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">207</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_ALREADY_REPORTED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">208</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_IM_USED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">226</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_MULTIPLE_CHOICES</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">300</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_STATUS_MOVED_PERMANENTLY</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">301</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_FOUND</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">302</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_SEE_OTHER</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">303</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NOT_MODIFIED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">304</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_USE_PROXY</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">305</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_TEMPORARY_REDIRECT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">307</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PERMANENT_REDIRECT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">308</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_BAD_REQUEST</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">400</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_UNAUTHORIZED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">401</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PAYMENT_REQUIRED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">402</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_FORBIDDEN</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">403</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NOT_FOUND</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">404</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_METHOD_NOT_ALLOWED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">405</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NOT_ACCEPTABLE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">406</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">407</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_REQUEST_TIMEOUT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">408</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_CONFLICT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">409</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_GONE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">410</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_LENGTH_REQUIRED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">411</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PRECONDITION_FAILED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">412</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PAYLOAD_TOO_LARGE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">413</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_ENTITY_TOO_LONG</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">414</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">415</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">416</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_EXPECTATION_FAILED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">417</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_TEAPOT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">418</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">422</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_LOCKED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">423</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_FAILED_DEPENDENCY</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">424</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_UPGRADE_REQUIRED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">426</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_PRECONDITION_REQUIRED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">428</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_TOO_MANY_REQUESTS</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">429</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_HEADERS_TOO_LARGE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">431</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">451</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">500</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NOT_IMPLEMENTED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">501</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_BAD_GATEWAY</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">502</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_SERVICE_UNAVAILABLE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">503</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_GATEWAY_TIMEOUT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">504</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">505</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">506</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_INSUFFICIENT_STORAGE</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">507</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_LOOP_DETECTED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">508</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NOT_EXTENDED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">510</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">511</span><span class="tok-p">,</span> +<span class="tok-p">};</span></code></pre> +</div> +</div> +<div class="paragraph"> +<p>Please see the relevant HTTP RFCs for the semantics and correct +use of these status codes.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It is a good idea to also set the reason message with +<a href="nng_http_res_set_reason.3http.html"><code>nng_http_set_reason()</code></a>. +This will help any humans who may have to diagnose a failure. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_res_get_status.3http.html">nng_http_req_get_status(3http)</a>, +<a href="nng_http_res_set_reason.3http.html">nng_http_req_set_reason(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_res_set_version.3http.html b/man/v1.7.2/nng_http_res_set_version.3http.html new file mode 100644 index 00000000..256a8482 --- /dev/null +++ b/man/v1.7.2/nng_http_res_set_version.3http.html @@ -0,0 +1,111 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_res_set_version(3http) +--- +<h1>nng_http_res_set_version(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_res_set_version - set HTTP response protocol version</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_res_set_version</span><span class="tok-p">(</span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">res</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">version</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_res_set_version()</code> sets the HTTP protocol version associated with +the response <em>res</em> to <em>version</em>. +The <em>version</em> must be a string containing +a valid HTTP protocol version, such as "HTTP/1.0". +The default value is "HTTP/1.1".</p> +</div> +<div class="paragraph"> +<p>A local copy of the <em>version</em> is made in the response <em>res</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +No validation of the version supplied is performed. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The library does not contain support for versions of HTTP other than +"HTTP/1.0" and "HTTP/1.1". +Specifying any other version may result in unspecified behavior. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>No support for HTTP in the library.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc.3http.html">nng_http_res_alloc(3http)</a>, +<a href="nng_http_req_get_version.3http.html">nng_http_req_get_version(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_server_add_handler.3http.html b/man/v1.7.2/nng_http_server_add_handler.3http.html new file mode 100644 index 00000000..2db51daa --- /dev/null +++ b/man/v1.7.2/nng_http_server_add_handler.3http.html @@ -0,0 +1,101 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_server_add_handler(3http) +--- +<h1>nng_http_server_add_handler(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_server_add_handler - add HTTP server handler</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_server_add_handler</span><span class="tok-p">(</span><span class="tok-n">nng_http_server</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">h</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_server_add_handler()</code> adds the handler <em>h</em> to the server +instance <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>If another handler is already added to the server that would conflict +with handler <em>h</em>, then the operation will fail with <code>NNG_EADDRINUSE</code>.</p> +</div> +<div class="paragraph"> +<p>If a handler is added to a server, and the server is subsequently +deallocated, the handler and any of its resources will also be deallocated.</p> +</div> +<div class="paragraph"> +<p>Handlers that are added to a server may be subsequently removed using the +<a href="nng_http_server_del_handler.3http.html"><code>nng_http_server_del_handler()</code></a> function.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINUSE</code> +</td> +<td class="hdlist2"> +<p>Handler conflicts with another handler.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_handler_alloc.3http.html">nng_http_handler_alloc(3http)</a>, +<a href="nng_http_server_del_handler.3http.html">nng_http_server_del_handler(3http)</a>, +<a href="nng_http_server_hold.3http.html">nng_http_server_hold(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_server_del_handler.3http.html b/man/v1.7.2/nng_http_server_del_handler.3http.html new file mode 100644 index 00000000..e51a9eb3 --- /dev/null +++ b/man/v1.7.2/nng_http_server_del_handler.3http.html @@ -0,0 +1,84 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_server_del_handler(3http) +--- +<h1>nng_http_server_del_handler(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_server_del_handler - delete HTTP server handler</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_server_del_handler</span><span class="tok-p">(</span><span class="tok-n">nng_http_server</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_http_handler</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">h</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_server_del_handler()</code> removes the handler <em>h</em> from the server +instance <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>Once a handler has been deleted from a server, it is the responsibility +of the caller to dispose of the handler, or add it to another server instance.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOENT</code> +</td> +<td class="hdlist2"> +<p>Handler is not registered with server.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_handler_free.3http.html">nng_http_handler_free(3http)</a>, +<a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_server_get_addr.3http.html b/man/v1.7.2/nng_http_server_get_addr.3http.html new file mode 100644 index 00000000..f27c8fef --- /dev/null +++ b/man/v1.7.2/nng_http_server_get_addr.3http.html @@ -0,0 +1,75 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_server_get_addr(3http) +--- +<h1>nng_http_server_get_addr(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_server_get_addr - get HTTP server address</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_server_get_addr</span><span class="tok-p">(</span><span class="tok-n">nng_http_server</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">server</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sap</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_http_server_get_addr()</code></dt> +<dd> +<p>This function is used to retrieve an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +into the value referenced by <em>sap</em> for the server <em>server</em>.</p> +</dd> +</dl> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_EINVAL</code></dt> +<dd> +<p>Either <em>server</em> or <em>sap</em> parameter is NULL.</p> +</dd> +<dt class="hdlist1"><code>NNG_ENOTSUP</code></dt> +<dd> +<p>HTTP not supported.</p> +</dd> +</dl> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_server_get_tls.3http.html b/man/v1.7.2/nng_http_server_get_tls.3http.html new file mode 100644 index 00000000..182d3319 --- /dev/null +++ b/man/v1.7.2/nng_http_server_get_tls.3http.html @@ -0,0 +1,100 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_server_get_tls(3http) +--- +<h1>nng_http_server_get_tls(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_server_get_tls - get HTTP server TLS configuration</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_server_get_tls</span><span class="tok-p">(</span><span class="tok-n">nng_http_server</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">cfgp</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_server_get_tls()</code> obtains the TLS configuration of server <em>s</em> and +saves a pointer to it in the address referenced by <em>cfgp</em>.</p> +</div> +<div class="paragraph"> +<p>The object will be returned with an extra hold (see +<a href="nng_tls_config_hold.3tls.html"><code>nng_tls_config_hold()</code></a>) +placed on it on behalf of the caller. +The caller should free this hold by calling +<a href="nng_tls_config_free.3tls.html"><code>nng_tls_config_free()</code></a> with it is done +with the TLS configuration.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>TLS not configured on server.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>Either HTTP or TLS not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_server_hold.3http.html">nng_http_server_hold(3http)</a>, +<a href="nng_http_server_set_tls.3http.html">nng_http_server_set_tls(3http)</a>, +<a href="nng_http_server_start.3http.html">nng_http_server_start(3http)</a>, +<a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_tls_config_free.3tls.html">nng_tls_config_free(3tls)</a>, +<a href="nng_tls_config_hold.3tls.html">nng_tls_config_hold(3tls)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_server_hold.3http.html b/man/v1.7.2/nng_http_server_hold.3http.html new file mode 100644 index 00000000..229ba6e8 --- /dev/null +++ b/man/v1.7.2/nng_http_server_hold.3http.html @@ -0,0 +1,111 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_server_hold(3http) +--- +<h1>nng_http_server_hold(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_server_hold - get and hold HTTP server instance</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_server_hold</span><span class="tok-p">(</span><span class="tok-n">nng_http_server</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">serverp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-n">nng_url</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_server_hold()</code> acquires an instance of an HTTP server suitable +for use in serving the URL identified by <em>url</em>, and stores a pointer to it +at the location pointed to by <em>serverp</em>.</p> +</div> +<div class="paragraph"> +<p>This function first looks to see if an existing HTTP server instance exists, +that is suitable for this. +If so, it increments the reference count on it and uses that. +Otherwise, it will attempt to create a new server instance +with an initial reference count of one (1).</p> +</div> +<div class="paragraph"> +<p>The server instance is not started, and can have additional configuration +applied to it before it is later started with +<a href="nng_http_server_start.3http.html"><code>nng_http_server_start()</code></a>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The URL matching logic in determining servers is unable to distinguish +between different aliases for the same local IP address. +This may create problems when using URLs for virtual hosting. +It is recommended to use canonical IP addresses or names in the +<em>url</em> to avoid confusion. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_server_add_handler.3http.html">nng_http_server_add_handler(3http)</a>, +<a href="nng_http_server_release.3http.html">nng_http_server_release(3http)</a>, +<a href="nng_http_server_stop.3http.html">nng_http_server_stop(3http)</a>, +<a href="nng_url_parse.3.html">nng_url_parse(3)</a> +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_server_release.3http.html b/man/v1.7.2/nng_http_server_release.3http.html new file mode 100644 index 00000000..d861e995 --- /dev/null +++ b/man/v1.7.2/nng_http_server_release.3http.html @@ -0,0 +1,83 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_server_release(3http) +--- +<h1>nng_http_server_release(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_server_release - release HTTP server instance</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_server_release</span><span class="tok-p">(</span><span class="tok-n">nng_http_server</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">server</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_server_release()</code> releases an instance of an HTTP <em>server</em> +that was previously held with +<a href="nng_http_server_hold.3http.html"><code>nng_http_server_hold()</code></a>.</p> +</div> +<div class="paragraph"> +<p>This effectively drops the reference count on the server instance. When +the reference count drops to zero, then the <em>server</em> and all resources +associated with it (e.g. HTTP handlers, connections, etc.) are deallocated. +(If the server is "running" when this occurs, then the server is stopped.)</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +It is an error to release an instance of a server that has +not previously been held, or to attempt to release an instance more +times than it has been held. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_server_hold.3http.html">nng_http_server_hold(3http)</a>, +<a href="nng_http_server_stop.3http.html">nng_http_server_stop(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_server_res_error.3http.html b/man/v1.7.2/nng_http_server_res_error.3http.html new file mode 100644 index 00000000..f8855c00 --- /dev/null +++ b/man/v1.7.2/nng_http_server_res_error.3http.html @@ -0,0 +1,98 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_server_res_error(3http) +--- +<h1>nng_http_server_res_error(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_server_res_error - use HTTP server error page</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_server_res_error</span><span class="tok-p">(</span><span class="tok-n">nng_http_server</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">server</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">nng_http_res</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">response</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_server_res_error()</code> sets the body of <em>response</em> +to <em>server</em>'s error page, which may have been customized using the +<a href="nng_http_server_set_error_file.3http.html"><code>nng_http_server_error_file()</code></a> +or +<a href="nng_http_server_set_error_page.3http.html"><code>nng_http_server_error_page()</code></a> +functions.</p> +</div> +<div class="paragraph"> +<p>The status code of the <em>response</em> should have already been set, either +implicitly by allocating it with +<a href="nng_http_res_alloc_error.3http.html"><code>nng_http_res_alloc_error()</code></a>, +or by calling +<a href="nng_http_res_set_status.3http.html"><code>nng_http_res_set_status()</code></a>.</p> +</div> +<div class="paragraph"> +<p>Any content body previously set for <em>response</em> will be overridden by +this function.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc_error.3http.html">nng_http_res_alloc_error(3http)</a>, +<a href="nng_http_server_hold.3http.html">nng_http_server_hold(3http)</a>, +<a href="nng_http_server_set_error_file.3http.html">nng_http_server_set_error_file(3http)</a>, +<a href="nng_http_server_set_error_page.3http.html">nng_http_server_set_error_page(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_server_set_error_file.3http.html b/man/v1.7.2/nng_http_server_set_error_file.3http.html new file mode 100644 index 00000000..21b3d483 --- /dev/null +++ b/man/v1.7.2/nng_http_server_set_error_file.3http.html @@ -0,0 +1,141 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_server_set_error_file(3http) +--- +<h1>nng_http_server_set_error_file(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_server_set_error_file - set custom HTTP error file</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_server_set_error_file</span><span class="tok-p">(</span><span class="tok-n">nng_http_server</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">server</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">code</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_server_set_error_file()</code> sets an error page to be used +for HTTP status <em>code</em> on the server instance <em>server</em>. +The body content of the HTTP responses will contain the file contents of +the file located at <em>path</em>, which should be an HTML file.</p> +</div> +<div class="paragraph"> +<p>The custom HTML content will be used when the server is returning an +internally generated error response, or is returning an error response +that was allocated with the +<a href="nng_http_res_alloc_error.3http.html"><code>nng_http_res_alloc_error()</code></a> +function. +This HTML content will also be used if the application calls the +<a href="nng_http_server_res_error.3http.html"><code>nng_http_server_res_error()</code></a>. +The last custom error page set for <em>code</em> by either this function or +xref:`nng_http_server_set_error_page.3http.adoc[<code>nng_http_server_error_page()</code>] +will be used.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Error responses that have their body content changed after allocation, +or that are written directly by the application, will not use the body +content supplied here. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The file contents of <em>path</em> are read when this function is called. +Therefore, if the file contents are changed, then this function should +be called again to update the error page. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOENT</code> +</td> +<td class="hdlist2"> +<p>The file named by <em>path</em> does not exist.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EPERM</code> +</td> +<td class="hdlist2"> +<p>No permission to read the file named by <em>path</em>.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc_error.3http.html">nng_http_res_alloc_error(3http)</a>, +<a href="nng_http_server_hold.3http.html">nng_http_server_hold(3http)</a>, +<a href="nng_http_server_res_error.3http.html">nng_http_server_res_error(3http)</a>, +<a href="nng_http_server_set_error_page.3http.html">nng_http_server_set_error_page(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_server_set_error_page.3http.html b/man/v1.7.2/nng_http_server_set_error_page.3http.html new file mode 100644 index 00000000..c8a5e492 --- /dev/null +++ b/man/v1.7.2/nng_http_server_set_error_page.3http.html @@ -0,0 +1,114 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_server_set_error_page(3http) +--- +<h1>nng_http_server_set_error_page(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_server_set_error_page - set custom HTTP error page</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_server_set_error_page</span><span class="tok-p">(</span><span class="tok-n">nng_http_server</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">server</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">code</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">html</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_server_set_error_page()</code> sets an error page to be used +for HTTP status <em>code</em> on the server instance <em>server</em>. +The body content of the HTTP responses will contain <em>html</em>.</p> +</div> +<div class="paragraph"> +<p>The custom HTML content will be used when the server is returning an +internally generated error response, or is returning an error response +that was allocated with the +<a href="nng_http_res_alloc_error.3http.html"><code>nng_http_res_alloc_error()</code></a> +function. +This HTML content will also be used if the application calls the +<a href="nng_http_server_res_error.3http.html"><code>nng_http_server_res_error()</code></a>. +The last custom error page set for <em>code</em> by either this function or +<a href="nng_http_server_set_error_file.3http.html"><code>nng_http_server_error_file()</code></a> +will be used.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Error responses that have their body content changed after allocation, +or that are written directly by the application, will not use the body +content supplied here. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The supplied HTML content is copied by this function, and may be reused +after this function returns.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_res_alloc_error.3http.html">nng_http_res_alloc_error(3http)</a>, +<a href="nng_http_server_hold.3http.html">nng_http_server_hold(3http)</a>, +<a href="nng_http_server_res_error.3http.html">nng_http_server_res_error(3http)</a>, +<a href="nng_http_server_set_error_file.3http.html">nng_http_server_set_error_file(3http)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_server_set_tls.3http.html b/man/v1.7.2/nng_http_server_set_tls.3http.html new file mode 100644 index 00000000..66a43e11 --- /dev/null +++ b/man/v1.7.2/nng_http_server_set_tls.3http.html @@ -0,0 +1,124 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_server_set_tls(3http) +--- +<h1>nng_http_server_set_tls(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_server_set_tls - set HTTP server TLS configuration</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_server_set_tls</span><span class="tok-p">(</span><span class="tok-n">nng_http_server</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cfg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_server_set_tls()</code> sets the TLS configuration of server <em>s</em> to +<em>cfg</em>.</p> +</div> +<div class="paragraph"> +<p>This change overwrites any previous TLS configuration.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This also invalidates any previously obtained values from +<a href="nng_http_server_get_tls.3http.html"><code>nng_http_server_get_tls()</code></a>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>If the server is already running (i.e. it has been started with +<a href="nng_http_server_start.3http.html"><code>nng_http_server_start()</code></a>) then this will +fail with <code>NNG_EBUSY</code>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Generally, the <em>cfg</em> must have a configured private key, set with +<a href="nng_tls_config_own_cert.3tls.html"><code>nng_tls_config_own_cert()</code></a> or similar. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBUSY</code> +</td> +<td class="hdlist2"> +<p>Server instance is running.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>Either HTTP or TLS not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_server_get_tls.3http.html">nng_http_server_get_tls(3http)</a>, +<a href="nng_http_server_hold.3http.html">nng_http_server_hold(3http)</a>, +<a href="nng_http_server_start.3http.html">nng_http_server_start(3http)</a>, +<a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_server_start.3http.html b/man/v1.7.2/nng_http_server_start.3http.html new file mode 100644 index 00000000..73ed219e --- /dev/null +++ b/man/v1.7.2/nng_http_server_start.3http.html @@ -0,0 +1,99 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_server_start(3http) +--- +<h1>nng_http_server_start(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_server_start - start HTTP server</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_http_server_start</span><span class="tok-p">(</span><span class="tok-n">nng_http_server</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">server</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_server_start()</code> starts the HTTP server instance <em>server</em>. +This causes it to bind to the appropriate TCP port, and start accepting +connections and handling HTTP requests.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINUSE</code> +</td> +<td class="hdlist2"> +<p>The TCP port is unavailable.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINVAL</code> +</td> +<td class="hdlist2"> +<p>The server is configured with an invalid address.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>HTTP not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_server_hold.3http.html">nng_http_server_hold(3http)</a>, +<a href="nng_http_server_release.3http.html">nng_http_server_release(3http)</a>, +<a href="nng_http_server_stop.3http.html">nng_http_server_stop(3http)</a>, +<a href="nng_url_parse.3.html">nng_url_parse(3)</a> +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_http_server_stop.3http.html b/man/v1.7.2/nng_http_server_stop.3http.html new file mode 100644 index 00000000..33fdc8ed --- /dev/null +++ b/man/v1.7.2/nng_http_server_stop.3http.html @@ -0,0 +1,89 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_http_server_stop(3http) +--- +<h1>nng_http_server_stop(3http)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_http_server_stop - stop HTTP server</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/http/http.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_http_server_stop</span><span class="tok-p">(</span><span class="tok-n">nng_http_server</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">server</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_http_server_stop()</code> undoes the effect of +<a href="nng_http_server_start.3http.html"><code>nng_http_server_start()</code></a>.</p> +</div> +<div class="paragraph"> +<p>Each call by +<a href="nng_http_server_start.3http.html"><code>nng_http_server_start()</code></a> acts as reference +count, and should be matched by a call to <code>nng_http_server_stop()</code>. +When the reference count drops to zero, then the server is actually stopped, +and existing open connections to it are closed.</p> +</div> +<div class="paragraph"> +<p>This function does not wait for the connections to close.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Once the server instance is actually stopped, it cannot be started again, +and any future calls to <a href="nng_http_server_hold.3http.html"><code>nng_http_server_hold()</code></a> +will return a new instance of the server. +It is expected that the caller will follow this function call with a call to +<a href="nng_http_server_release.3http.html"><code>nng_http_server_release()</code></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_http_server_hold.3http.html">nng_http_server_hold(3http)</a>, +<a href="nng_http_server_release.3http.html">nng_http_server_release(3http)</a>, +<a href="nng_http_server_start.3http.html">nng_http_server_start(3http)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_id_map.3supp.html b/man/v1.7.2/nng_id_map.3supp.html new file mode 100644 index 00000000..5fea4a97 --- /dev/null +++ b/man/v1.7.2/nng_id_map.3supp.html @@ -0,0 +1,165 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_id_map(3supp) +--- +<h1>nng_id_map(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_id_map - identifier based mapping table</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/idhash.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_id_map_s</span><span class="tok-w"> </span><span class="tok-n">nng_id_map</span><span class="tok-p">;</span> + +<span class="tok-cp">#define NNG_MAP_RANDOM 1</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_id_map_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_id_map</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">map_p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">lo</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">hi</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span> +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_id_map_free</span><span class="tok-p">(</span><span class="tok-n">nng_id_map</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">map</span><span class="tok-p">);</span> +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_id_get</span><span class="tok-p">(</span><span class="tok-n">nng_id_map</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">map</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">id</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_id_set</span><span class="tok-p">(</span><span class="tok-n">nng_id_map</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">map</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">value</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_id_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_id_map</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">map</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">id_p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">value</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_id_remove</span><span class="tok-p">(</span><span class="tok-n">nng_id_map</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">map</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">id</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions provide support for managing tables of data based on +identifiers, ensuring that identifiers are allocated uniquely and within +specified range limits.</p> +</div> +<div class="paragraph"> +<p>The table stores data pointers (which must not be <code>NULL</code>) at a logical numeric index. +It does so efficiently, even if large gaps exist, and it provides a means to efficiently +allocate a numeric identifier from a pool of unused identifiers.</p> +</div> +<div class="paragraph"> +<p>Identifiers are allocated in increasing order, without reusing old identifiers until the +largest possible identifier is allocated. After wrapping, only identifiers that are no longer +in use will be considered. +No effort to order the availability of identifiers based on when they were freed is made.</p> +</div> +<div class="paragraph"> +<p>An initial table is allocated with <code>nng_id_map_alloc()</code>, which takes the lowest legal identifier in <em>lo</em>, +and the largest legal identifier in <em>hi</em>. +The new table is returned in <em>map_p</em>, and should be used as the <em>map</em> argument to the rest of these functions.</p> +</div> +<div class="sidebarblock"> +<div class="content"> +<div class="paragraph"> +<p>As a special convenience, if these are specified as zero, then a full range of 32-bit identifiers is assumed. +If identifiers larger than or equal to 2<sup>32</sup> are required, then both <em>lo</em> and <em>hi</em> must be specified with the +exact values desired.</p> +</div> +</div> +</div> +<div class="paragraph"> +<p>The <em>flags</em> argument is a bit mask of flags for the table. +If <code>NNG_MAP_RANDOM</code> is specified, then the starting point for allocations is randomized, but subsequent allocations will then be monotonically increasing. +This is useful to reduce the odds of different instances of an application using the same identifiers at the same time.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_id_get()</code> function returns the value previously stored with the given identifier. +If no value is currently associated with the identifer, it returns <code>NULL</code>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_id_set()</code> function sets the value with the associated identifier. +This can be used to replace a previously allocated identifier. +If the identifier was not previously allocated, then it is allocated as part of the call. +This function does not necessarily honor the identifier range limits set for the map when it was allocated.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_id_alloc()</code> function allocates a new identifier from the range for the map, and associates it with +the supplied <em>value</em>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_id_remove()</code> function removes the identifier and its associated value from the table.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +These functions are limited to storing at most 2<sup>32</sup> identifiers, even though the identifers may +themselves be larger than 2<sup>32</sup>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +These functions are <strong>not</strong> thread-safe. +Callers should use a <a href="nng_mtx_lock.3supp">mutex</a> or similar approach when thread-safety is needed. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_id_map_alloc()</code>, <code>nng_id_set()</code>, <code>nng_id_alloc()</code>, and <code>nng_id_remove()</code> functions +return 0 on success, or -1 on failure.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_id_map_get()</code> function returns the requested data pointer, or <code>NULL</code> if the identifier was not found.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOENT</code> +</td> +<td class="hdlist2"> +<p>The <em>id</em> does not exist in the table.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available, or the table is full.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_mtx_lock.3supp.html">nng(7)</a> +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_inproc.7.html b/man/v1.7.2/nng_inproc.7.html new file mode 100644 index 00000000..23323eeb --- /dev/null +++ b/man/v1.7.2/nng_inproc.7.html @@ -0,0 +1,107 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_inproc(7) +--- +<h1>nng_inproc(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_inproc - intra-process transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/inproc/inproc.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_inproc_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> + +The <em>inproc</em> transport provides communication support between +sockets within the same process. +This may be used as an alternative +to slower transports when data must be moved within the same process.</p> +</div> +<div class="paragraph"> +<p>This transport tries hard to avoid copying data, and thus is very +light-weight.</p> +</div> +<div class="sect2"> +<h3 id="_registration">Registration</h3> +<div class="paragraph"> +<p>This transport is generally built-in to the core, so +no extra steps to use it should be necessary.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_uri_format">URI Format</h3> +<div class="paragraph"> +<p> +This transport uses URIs using the scheme <code>inproc://</code>, followed by +an arbitrary string of text, terminated by a <code>NUL</code> byte.</p> +</div> +<div class="paragraph"> +<p>Multiple URIs can be used within the +same application, and they will not interfere with one another.</p> +</div> +<div class="paragraph"> +<p>Two applications may also use the same URI without interfering with each +other, and they will be unable to communicate with each other using +that URI.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_socket_address">Socket Address</h3> +<div class="paragraph"> +<p>When using an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> structure, +the actual structure is of type +<a href="nng_sockaddr_inproc.5.html"><code>nng_sockaddr_inproc</code></a>.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_transport_options">Transport Options</h3> +<div class="paragraph"> +<p>The <em>inproc</em> transport has no special options.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +While <em>inproc</em> accepts the option +<a href="nng_options.5.html#NNG_OPT_RECVMAXSZ"><code>NNG_OPT_RECVMAXSZ</code></a> for +compatibility, the value of the option is ignored with no enforcement. +As <em>inproc</em> peers are in the same address space, they are implicitly trusted, +and thus it makes no sense to spend cycles protecting a program from itself. +</td> +</tr> +</table> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_inproc_register.3.html">nng_inproc_register(3)</a>, +<a href="nng_sockaddr_inproc.5.html">nng_sockaddr_inproc(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_inproc_register.3.html b/man/v1.7.2/nng_inproc_register.3.html new file mode 100644 index 00000000..847203a5 --- /dev/null +++ b/man/v1.7.2/nng_inproc_register.3.html @@ -0,0 +1,90 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_inproc_register(3) +--- +<h1>nng_inproc_register(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_inproc_register - register inproc transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/inproc/inproc.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_inproc_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_inproc_register()</code> function registers the +<em>inproc</em> transport for use.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The transport is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_inproc.7.html">nng_inproc(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_iov.5.html b/man/v1.7.2/nng_iov.5.html new file mode 100644 index 00000000..065a2c88 --- /dev/null +++ b/man/v1.7.2/nng_iov.5.html @@ -0,0 +1,73 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_iov(5) +--- +<h1>nng_iov(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_iov - scatter/gather element</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-w"> </span><span class="tok-n">iov_buf</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">iov_len</span><span class="tok-p">;</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_iov</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>An <code>nng_iov</code> structure represents a single element in a scatter/gather +array. +Some operations can use arrays of these to access different regions of +memory in a single operation. +For example, it may be useful to send a message with header data from +one part of memory, and a user payload from another.</p> +</div> +<div class="paragraph"> +<p>The operations that do this typically store an array of these in +an <a href="nng_aio.5.html"><code>nng_aio</code></a> structure using the +<a href="nng_aio_set_iov.3.html"><code>nng_aio_set_iov()</code></a> function.</p> +</div> +<div class="paragraph"> +<p>The following structure members are present:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>iov_buf</code></dt> +<dd> +<p>This is a pointer to the first byte within the memory being +referenced by this scatter/gather element.</p> +</dd> +<dt class="hdlist1"><code>iov_len</code></dt> +<dd> +<p>This is the size in bytes of this scatter/gather element.</p> +</dd> +</dl> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_set_iov.3.html">nng_aio_set_iov(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ipc.7.html b/man/v1.7.2/nng_ipc.7.html new file mode 100644 index 00000000..7480303b --- /dev/null +++ b/man/v1.7.2/nng_ipc.7.html @@ -0,0 +1,230 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ipc(7) +--- +<h1>nng_ipc(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ipc - IPC transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/ipc/ipc.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ipc_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>ipc</em> transport provides communication support between +sockets within different processes on the same host. +For POSIX platforms, this is implemented using UNIX domain sockets. +For Windows, this is implemented using Windows Named Pipes. +Other platforms may have different implementation strategies.</p> +</div> +<div class="sect2"> +<h3 id="_registration">Registration</h3> +<div class="paragraph"> +<p>This transport is generally built-in to the core, so +no extra steps to use it should be necessary.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_uri_formats">URI Formats</h3> +<div class="sect3"> +<h4 id="_traditional_names">Traditional Names</h4> +<div class="paragraph"> +<p> +This transport uses URIs using the scheme <code>ipc://</code>, followed by a path +name in the file system where the socket or named pipe should be created.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +On Windows, all names are prefixed by <code>\\.\pipe\</code> and do not +reside in the normal file system. +On POSIX platforms, the path is taken literally, and is relative to +the current directory, unless it begins with <code>/</code>, in which case it is +relative to the root directory. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +When using relative paths on POSIX systems, the address used and returned +in properties like <code>NNG_OPT_LOCADDR</code> and <code>NNG_OPT_URL</code> will also be relative. +Consequently, they will only be interpreted the same by processes that have +the same working directory. +To ensure maximum portability and safety, absolute paths are recommended +whenever possible. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +If compatibility with legacy <em>nanomsg</em> applications is required, +then path names must not be longer than 122 bytes, including the final +<code>NUL</code> byte. +This is because legacy versions of <em>nanomsg</em> cannot express URLs +longer than 128 bytes, including the <code>ipc://</code> prefix. +</td> +</tr> +</table> +</div> +</div> +<div class="sect3"> +<h4 id="_unix_aliases">UNIX Aliases</h4> +<div class="paragraph"> +<p> +The <code>unix://</code> scheme is an alias for <code>ipc://</code> and can be used inter-changeably, but only +on POSIX systems.</p> +</div> +<div class="paragraph"> +<p>The purpose of this scheme is to support a future transport making use of <code>AF_UNIX</code> +on Windows systems, at which time it will be necessary to discriminate between +the Named Pipes and the <code>AF_UNIX</code> based transports.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_abstract_names">Abstract Names</h4> +<div class="paragraph"> +<p> +On Linux, this transport also can support abstract sockets. +Abstract sockets use a URI-encoded name after the scheme, which allows arbitrary values to be conveyed +in the path, including embedded <code>NUL</code> bytes. +For example, the name <code>"a\0b"</code> would be represented as <code>abstract://a%00b</code>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +An empty name may be used with a listener to request “auto bind” be used to select a name. +In this case the system will allocate a free name. +The name assigned may be retrieved using <code>NNG_OPT_LOCADDR</code>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +<em>NNG</em> cannot represent an abstract socket with the empty name. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Abstract names do not include the leading <code>NUL</code> byte used in the low-level socket address. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Abstract sockets do not have any representation in the file system, and are automatically freed by +the system when no longer in use. +Abstract sockets ignore socket permissions, but it is still possible to determine the credentials +of the peer with <code>NNG_OPT_PEER_UID</code>, etc.</p> +</div> +</div> +</div> +<div class="sect2"> +<h3 id="_socket_address">Socket Address</h3> +<div class="paragraph"> +<p>When using an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> structure, +the actual structure is of type <a href="nng_sockaddr_ipc.5.html"><code>nng_sockaddr_ipc</code></a>, +except for abstract sockets, which use <a href="nng_sockaddr_abstract.5.html"><code>nng_sockaddr_abstract</code></a>.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_transport_options">Transport Options</h3> +<div class="paragraph"> +<p>The following transport options are supported by this transport, +where supported by the underlying platform.</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><a href="nng_ipc_options.5.html#NNG_OPT_IPC_PERMISSIONS"><code>NNG_OPT_IPC_PERMISSIONS</code></a></p> +</li> +<li> +<p><a href="nng_ipc_options.5.html#NNG_OPT_IPC_SECURITY_DESCRIPTOR"><code>NNG_OPT_IPC_SECURITY_DESCRIPTOR</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_LOCADDR"><code>NNG_OPT_LOCADDR</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_REMADDR"><code>NNG_OPT_REMADDR</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_PEER_GID"><code>NNG_OPT_PEER_GID</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_PEER_PID"><code>NNG_OPT_PEER_PID</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_PEER_UID"><code>NNG_OPT_PEER_UID</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_PEER_ZONEID"><code>NNG_OPT_PEER_ZONEID</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_URL"><code>NNG_OPT_URL</code></a></p> +</li> +</ul> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng_ipc_options.5.html">nng_ipc_options(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ipc_options.5.html b/man/v1.7.2/nng_ipc_options.5.html new file mode 100644 index 00000000..b326652f --- /dev/null +++ b/man/v1.7.2/nng_ipc_options.5.html @@ -0,0 +1,200 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ipc_options(5) +--- +<h1>nng_ipc_options(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ipc_options - IPC-specific options</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-cp">#define NNG_OPT_IPC_PEER_GID "ipc:peer-gid"</span> +<span class="tok-cp">#define NNG_OPT_IPC_PEER_PID "ipc:peer-pid"</span> +<span class="tok-cp">#define NNG_OPT_IPC_PEER_UID "ipc:peer-uid"</span> +<span class="tok-cp">#define NNG_OPT_IPC_PEER_ZONEID "ipc:peer-zoneid"</span> +<span class="tok-cp">#define NNG_OPT_IPC_PERMISSIONS "ipc:permissions"</span> +<span class="tok-cp">#define NNG_OPT_IPC_SECURITY_DESCRIPTOR "ipc:security-descriptor"</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This page documents the various standard options that can be set or +retrieved on objects using IPC.</p> +</div> +<div class="paragraph"> +<p>The option names should always be used by their symbolic definitions.</p> +</div> +<div class="paragraph"> +<p>In the following list of options, the name of the option is supplied, +along with the data type of the underlying value.</p> +</div> +<div class="paragraph"> +<p>Some options are only meaningful or supported in certain contexts, or may +have other access restrictions. +An attempt has been made to include details about such restrictions in the +description of the option.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The availability of the following options is platform-specific, +as the implementations of IPC are quite different on Windows and POSIX systems. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><a id="NNG_OPT_IPC_PERMISSIONS"></a><code>NNG_OPT_IPC_PERMISSIONS</code></dt> +<dd> +<p>(<code>int</code>) +This write-only option may be applied to a listener to configure the +permissions that are used on the UNIX domain socket created by that listener. +This property is only supported on POSIX systems. +The value is of type <code>int</code>, representing the normal permission bits +on a file, such as <code>0600</code> (typically meaning read-write to the owner, and +no permissions for anyone else.) +The default is system-specific, most often <code>0644</code>.</p> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Not all systems validate these permissions. +In particular, illumos and Solaris are known to ignore these permission +settings when connecting. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Normally both read and write permission will be necessary for a +peer dialer to connect. +See your system documentation for UNIX domain sockets for more information. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The <em>umask</em> of the process is <strong>not</strong> applied to these bits. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The best practice for limiting access is to place the socket in a +directory writable only by the server, and only readable and searchable +by clients. +All mainstream POSIX systems will fail to permit a client to connect +to a socket located in a directory for which the client lacks search (execute) +permission. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><a id="NNG_OPT_IPC_SECURITY_DESCRIPTOR"></a><code>NNG_OPT_IPC_SECURITY_DESCRIPTOR</code></dt> +<dd> +<p>(<code>PSECURITY_DESCRIPTOR</code>) +This write-only option may be used on listeners on Windows platforms to +configure the <code>SECURITY_DESCRIPTOR</code> that is used when creating the underlying +named pipe. +The value is a pointer, <code>PSECURITY_DESCRIPTOR</code>, and may only be +applied to listeners that have not been started yet.</p> +</dd> +</dl> +</div> +<div class="sect2"> +<h3 id="_common_platform_specific_options">Common Platform Specific Options</h3> +<div class="paragraph"> +<p>The following options are supported by this transport when the underlying platform supports them:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><a href="nng_options.5.html#NNG_OPT_PEER_GID"><code>NNG_OPT_PEER_GID</code></a> (also available as <code>NNG_OPT_IPC_PEER_GID</code>)</p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_PEER_PID"><code>NNG_OPT_PEER_PID</code></a> (also available as <code>NNG_OPT_IPC_PEER_PID</code>)</p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_PEER_UID"><code>NNG_OPT_PEER_UID</code></a> (also available as <code>NNG_OPT_IPC_PEER_UID</code>)</p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_PEER_ZONEID"><code>NNG_OPT_PEER_ZONEID</code></a> (also available as <code>NNG_OPT_IPC_PEER_ZONEID</code>)</p> +</li> +</ul> +</div> +</div> +<div class="sect2"> +<h3 id="_inherited_options">Inherited Options</h3> +<div class="paragraph"> +<p>Generally, the following option values are also available when appropriate for the context:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><a href="nng_options.5.html#NNG_OPT_LOCADDR"><code>NNG_OPT_LOCADDR</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_REMADDR"><code>NNG_OPT_REMADDR</code></a></p> +</li> +</ul> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer_get.3.html">nng_dialer_get(3)</a>, +<a href="nng_dialer_set.3.html">nng_dialer_set(3)</a>, +<a href="nng_listener_get.3.html">nng_listener_get(3)</a>, +<a href="nng_listener_set.3.html">nng_listener_set(3)</a>, +<a href="nng_pipe_get.3.html">nng_pipe_get(3)</a>, +<a href="nng_options.5.html">nng_options(5)</a> +<a href="nng.7.html">nng(7)</a>, +<a href="nng_ipc.7.html">nng_ipc(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ipc_register.3.html b/man/v1.7.2/nng_ipc_register.3.html new file mode 100644 index 00000000..b13bf17b --- /dev/null +++ b/man/v1.7.2/nng_ipc_register.3.html @@ -0,0 +1,90 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ipc_register(3) +--- +<h1>nng_ipc_register(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ipc_register - register ipc transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/ipc/ipc.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ipc_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_ipc_register()</code> function registers the +<em>ipc</em> transport for use.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The transport is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_ipc.7.html">nng_ipc(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_listen.3.html b/man/v1.7.2/nng_listen.3.html new file mode 100644 index 00000000..1ed20e98 --- /dev/null +++ b/man/v1.7.2/nng_listen.3.html @@ -0,0 +1,146 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_listen(3) +--- +<h1>nng_listen(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_listen - create and start listener</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listen</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">lp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_listen()</code> function creates a newly initialized +<a href="nng_listener.5.html"><code>nng_listener</code></a> object, associated with socket <em>s</em>, +and configured to listen at the address specified by <em>url</em>, and starts it. +If the value of <em>lp</em> is not <code>NULL</code>, then +the newly created listener is stored at the address indicated by <em>lp</em>.</p> +</div> +<div class="paragraph"> +<p>Listeners are used to accept connections initiated by remote dialers. +An incoming connection generally results in an +<a href="nng_pipe.5.html"><code>nng_pipe</code></a> object being created and attached to the socket <em>s</em>. +Unlike dialers, listeners generally can create many +pipes, which may be open concurrently.</p> +</div> +<div class="paragraph"> +<p>The <em>flags</em> argument is ignored, but reserved for future use.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +While it is convenient to think of listeners as servers, the +relationship between the listener or dialer is orthogonal to any server or +client status that might be associated with a given protocol. +For example, a <a href="nng_req.7.html"><em>req</em></a> +socket might have associated dialers, but might also have associated listeners. +It may even have some of each at the same time! +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Because the listener is started immediately, it is generally not possible +to apply extra configuration; if that is needed applications should consider +using <a href="nng_listener_create.3.html"><code>nng_listener_create()</code></a> and +<a href="nng_listener_start.3.html"><code>nng_listener_start()</code></a> instead.</p> +</div> +<div class="paragraph"> +<p>The created listener will continue to accept new connections, associating +their pipes with the socket, until either it or the socket <em>s</em> is closed.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINUSE</code> +</td> +<td class="hdlist2"> +<p>The address specified by <em>url</em> is already in use.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>url</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid set of <em>flags</em> or an invalid <em>url</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dial.3.html">nng_dial(3)</a>, +<a href="nng_listener_close.3.html">nng_listener_close(3)</a>, +<a href="nng_listener_create.3.html">nng_listener_create(3)</a> +<a href="nng_listener_start.3.html">nng_listener_start(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_listener.5.html b/man/v1.7.2/nng_listener.5.html new file mode 100644 index 00000000..8e46e7d7 --- /dev/null +++ b/man/v1.7.2/nng_listener.5.html @@ -0,0 +1,120 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_listener(5) +--- +<h1>nng_listener(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_listener - listener</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_listener_s</span><span class="tok-w"> </span><span class="tok-n">nng_listener</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +An <code>nng_listener</code> is a handle to a listener object, which is responsible for +creating <a href="nng_pipe.5.html"><code>nng_pipe</code></a> objects by accepting incoming connections. +A given listener object may create many pipes at the same time, much like an +HTTP server can have many connections to multiple clients simultaneously.</p> +</div> +<div class="paragraph"> +<p>Listener objects are created by the +<a href="nng_listener_create.3.html"><code>nng_listener_create()</code></a> +or <a href="nng_listen.3.html"><code>nng_listen()</code></a> functions, and are always associated +with a single <a href="nng_socket.5.html"><code>nng_socket</code></a>.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +The <code>nng_listener</code> structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way gives the compiler a chance to perform +accurate type checks in functions passing values of this type. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +A given <a href="nng_socket.5.html"><code>nng_socket</code></a> may have multiple listener +objects, multiple <a href="nng_dialer.5.html">dialer</a> objects, or even some +of both. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The client/server relationship described by dialer/listener is +completely orthogonal to any similar relationship in the protocols. +For example, a <a href="nng_rep.7.html"><em>rep</em></a> socket may use a dialer +to connect to a listener on an <a href="nng_req.7.html"><em>req</em></a> socket. +This orthogonality can lead to innovative solutions to otherwise +challenging communications problems. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Listener objects may be destroyed by the +<a href="nng_listener_close.3.html"><code>nng_listener_close()</code></a> function. +They are also closed when their associated socket is closed.</p> +</div> +<div class="sect2"> +<h3 id="NNG_LISTENER_INITIALIZER">Initialization</h3> +<div class="paragraph"> +<p>A listener may be initialized using the macro <code>NNG_LISTENER_INITIALIZER</code> +before it is opened, to prevent confusion with valid open listener.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_listen.3.html">nng_listen(3)</a>, +<a href="nng_listener_close.3.html">nng_listener_close(3)</a>, +<a href="nng_listener_create.3.html">nng_listener_create(3)</a>, +<a href="nng_listener_getopt.3.html">nng_listener_getopt(3)</a>, +<a href="nng_listener_id.3.html">nng_listener_id(3)</a>, +<a href="nng_listener_setopt.3.html">nng_listener_setopt(3)</a>, +<a href="nng_listener_start.3.html">nng_listener_start(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng_pipe.5.html">nng_pipe(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_listener_close.3.html b/man/v1.7.2/nng_listener_close.3.html new file mode 100644 index 00000000..b804686d --- /dev/null +++ b/man/v1.7.2/nng_listener_close.3.html @@ -0,0 +1,84 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_listener_close(3) +--- +<h1>nng_listener_close(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_listener_close - close listener</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_close</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_listener_close()</code> function closes the listener <em>l</em>. +This also closes any pipes that have been created by the listener.</p> +</div> +<div class="paragraph"> +<p>Once this function returns, the listener <em>l</em> and any of its resources +are deallocated. +Therefore it is an error to attempt to access <em>l</em> +after this function has returned. +(Attempts to do so will result in <code>NNG_ECLOSED</code> errors.)</p> +</div> +<div class="paragraph"> +<p>Listeners are implicitly closed when the socket they are associated with +is closed.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>l</em> does not refer to an open listener.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_close.3.html">nng_close(3)</a>, +<a href="nng_listen.3.html">nng_listen(3)</a>, +<a href="nng_listener_create.3.html">nng_listener_create(3)</a> +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_listener_create.3.html b/man/v1.7.2/nng_listener_create.3.html new file mode 100644 index 00000000..85c2ef52 --- /dev/null +++ b/man/v1.7.2/nng_listener_create.3.html @@ -0,0 +1,140 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_listener_create(3) +--- +<h1>nng_listener_create(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_listener_create - create listener</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_create</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">listenerp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_listener_create()</code> function creates a newly initialized +<a href="nng_listener.5.html"><code>nng_listener</code></a> object, associated with socket <em>s</em>, +and configured to listen at the address specified by <em>url</em>, +and stores a pointer to at the location referenced by <em>listenerp</em>.</p> +</div> +<div class="paragraph"> +<p>Listeners are used to accept connections initiated by remote dialers. +An incoming connection generally results in a pipe being created and attached +to the socket <em>s</em>. +Unlike dialers, listeners generally can create many pipes, +which may be open concurrently.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +While it is convenient to think of listeners as servers, the +relationship between the listener or dialer is orthogonal to any server or +client status that might be associated with a given protocol. +For example, a <a href="nng_req.7.html"><em>req</em></a> socket might have associated dialers, +but might also have associated listeners. +It may even have some of each at the same time! +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The listener is not started, but may be further configured with +the <a href="nng_listener_setopt.3.html"><code>nng_listener_setopt()</code></a> family of +functions.</p> +</div> +<div class="paragraph"> +<p>Once it is fully configured, the listener may be started using the +<a href="nng_listener_start.3.html"><code>nng_listener_start()</code></a> function.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +If no specific configuration is required, consider using the +simpler <a href="nng_listen.3.html"><code>nng_listen()</code></a> function instead. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>url</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer_create.3.html">nng_dialer_create(3)</a> +<a href="nng_listen.3.html">nng_listen(3)</a>, +<a href="nng_listener_close.3.html">nng_listener_close(3)</a>, +<a href="nng_listener_getopt.3.html">nng_listener_getopt(3)</a>, +<a href="nng_listener_setopt.3.html">nng_listener_setopt(3)</a>, +<a href="nng_listener_start.3.html">nng_listener_start(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_listener_get.3.html b/man/v1.7.2/nng_listener_get.3.html new file mode 100644 index 00000000..ef0c6a03 --- /dev/null +++ b/man/v1.7.2/nng_listener_get.3.html @@ -0,0 +1,237 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_listener_get(3) +--- +<h1>nng_listener_get(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_listener_get - get listener option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_get</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valszp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_get_bool</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">bvalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_get_int</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ivalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_get_ms</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">durp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_get_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_get_size</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">zp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_get_addr</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sap</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_get_string</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">strp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_get_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u64p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <code>nng_listener_get()</code> functions are used to retrieve option values for +the <a href="nng_listener.5.html">listener</a> <em>l</em>. +The actual options that may be retrieved in this way +vary, and many are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally some transport-specific options are documented with the transports themselves.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the listener <em>l</em>. +The forms vary based on the type of the option they take.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_listener_get()</code></dt> +<dd> +<p>This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in <em>val</em>, +and the size of the buffer shall be stored at the location referenced +by <em>valszp</em>.<br> +<br> +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>valszp</em>. +If the caller’s buffer is not large +enough to hold the entire object, then the copy is truncated. Therefore +the caller should validate that the returned size in <em>valszp</em> does not +exceed the original buffer size to check for truncation.<br> +<br> +It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>valszp</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_listener_get_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The value will be stored at <em>bvalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_get_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The value will be stored at <em>ivalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_get_ms()</code></dt> +<dd> +<p>This function is used to retrieve time <a href="nng_duration.5.html">durations</a> +(such as timeouts), stored in <em>durp</em> as a number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_get_ptr()</code></dt> +<dd> +<p>This function is used to retrieve a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_get_size()</code></dt> +<dd> +<p>This function is used to retrieve a size into the pointer <em>zp</em>, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_get_addr()</code></dt> +<dd> +<p>This function is used to retrieve an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +into the value referenced by <em>sap</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_get_string()</code></dt> +<dd> +<p>This function is used to retrieve a string into <em>strp</em>. +This string is created from the source using <a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_get_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value into the value +referenced by <em>u64p</em>. +This is typically used for options related to identifiers, network +numbers, and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>l</em> does not refer to an open listener.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Size of destination <em>val</em> too small for object.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is write-only.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_listen.3.html">nng_listen(3)</a>, +<a href="nng_listener_create.3.html">nng_listener_create(3)</a> +<a href="nng_listener_set.3.html">nng_listener_set(3)</a> +<a href="nng_socket_get.3.html">nng_socket_get(3)</a>, +<a href="nng_strdup.3.html">nng_strdup(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_strfree.3.html">nng_strfree(3)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_listener_getopt.3.html b/man/v1.7.2/nng_listener_getopt.3.html new file mode 100644 index 00000000..74a4decc --- /dev/null +++ b/man/v1.7.2/nng_listener_getopt.3.html @@ -0,0 +1,251 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_listener_getopt(3) +--- +<h1>nng_listener_getopt(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_listener_getopt - get listener option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_getopt</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valszp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_getopt_bool</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">bvalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_getopt_int</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ivalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_getopt_ms</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">durp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_getopt_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_getopt_size</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">zp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_getopt_sockaddr</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sap</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_getopt_string</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">strp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_getopt_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u64p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +These functions are deprecated. Please see <a href="nng_listener_get.3.html">nng_listener_get</a>. +They may not be present if the library was built with <code>NNG_ELIDE_DEPRECATED</code>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p> +The <code>nng_listener_getopt()</code> functions are used to retrieve option values for +the <a href="nng_listener.5.html">listener</a> <em>l</em>. +The actual options that may be retrieved in this way +vary, and many are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally some transport-specific options +are documented with the transports themselves.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the listener <em>l</em>. +The forms vary based on the type of the option they take.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_listener_getopt()</code></dt> +<dd> +<p>This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in <em>val</em>, +and the size of the buffer shall be stored at the location referenced +by <em>valszp</em>.<br> +<br> +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>valszp</em>. +If the caller’s buffer is not large +enough to hold the entire object, then the copy is truncated. Therefore +the caller should validate that the returned size in <em>valszp</em> does not +exceed the original buffer size to check for truncation.<br> +<br> +It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>valszp</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_listener_getopt_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The value will be stored at <em>bvalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_getopt_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The value will be stored at <em>ivalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_getopt_ms()</code></dt> +<dd> +<p>This function is used to retrieve time <a href="nng_duration.5.html">durations</a> +(such as timeouts), stored in <em>durp</em> as a number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_getopt_ptr()</code></dt> +<dd> +<p>This function is used to retrieve a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_getopt_size()</code></dt> +<dd> +<p>This function is used to retrieve a size into the pointer <em>zp</em>, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_getopt_sockaddr()</code></dt> +<dd> +<p>This function is used to retrieve an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +into the value referenced by <em>sap</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_getopt_string()</code></dt> +<dd> +<p>This function is used to retrieve a string into <em>strp</em>. +This string is created from the source using <a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_getopt_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value into the value +referenced by <em>u64p</em>. +This is typically used for options related to identifiers, network +numbers, and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>l</em> does not refer to an open listener.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Size of destination <em>val</em> too small for object.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is write-only.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_listen.3.html">nng_listen(3)</a>, +<a href="nng_listener_create.3.html">nng_listener_create(3)</a> +<a href="nng_listener_setopt.3.html">nng_listener_setopt(3)</a> +<a href="nng_getopt.3.html">nng_getopt(3)</a>, +<a href="nng_strdup.3.html">nng_strdup(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_strfree.3.html">nng_strfree(3)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_listener_id.3.html b/man/v1.7.2/nng_listener_id.3.html new file mode 100644 index 00000000..c24764c5 --- /dev/null +++ b/man/v1.7.2/nng_listener_id.3.html @@ -0,0 +1,80 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_listener_id(3) +--- +<h1>nng_listener_id(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_listener_id - return numeric listener identifier</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_id</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_listener_id()</code> function returns a positive identifier for the +listener <em>l</em>, if it is valid. +Otherwise it returns <code>-1</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +A listener is considered valid if it was ever created with the +<a href="nng_listener_create.3.html"><code>nng_listener_create()</code></a> or +<a href="nng_listen.3.html"><code>nng_listen()</code></a> functions. +listeners that are allocated on the stack or statically should be +initialized with the macro +<a href="nng_ctx.5.html#NNG_LISTENER_INITIALIZER"><code>NNG_LISTENER_INITIALIZER</code></a> to ensure that +they cannot be confused with a valid listener before they are created properly. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the positive value for the listener identifier, or +<code>-1</code> if the listener is invalid.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_listener_set.3.html b/man/v1.7.2/nng_listener_set.3.html new file mode 100644 index 00000000..c4e330e0 --- /dev/null +++ b/man/v1.7.2/nng_listener_set.3.html @@ -0,0 +1,242 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_listener_set(3) +--- +<h1>nng_listener_set(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_listener_set - set listener option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_set</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">valsz</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_set_bool</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">bval</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_set_int</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">ival</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_set_ms</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">dur</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_set_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_set_size</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">z</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_set_string</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">str</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_set_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">u64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <code>nng_listener_set()</code> functions are used to configure options for +the <a href="nng_listener.5.html">listener</a> <em>l</em>. +The actual options that may be configured in this way +vary, and many are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally some transport-specific options are documented with the transports themselves.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Once a listener has started, it is generally not possible to change +its configuration. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is configured on the listener <em>l</em>.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_listener_set()</code></dt> +<dd> +<p>This function is untyped, and can be used to configure any arbitrary data. +The <em>val</em> pointer addresses the data to copy, and <em>valsz</em> is the +size of the objected located at <em>val</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_set_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The <em>bval</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_set_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The <em>ival</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_set_ms()</code></dt> +<dd> +<p>This function is used to configure time durations (such as timeouts) using +type <a href="nng_duration.5.html"><code>nng_duration</code></a>. +The duration <em>dur</em> is an integer number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_set_ptr()</code></dt> +<dd> +<p>This function is used to pass a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed by other functions. +For example, TLS configuration objects created with +(<a href="nng_tls_config_alloc.3tls.html"><code>nng_tls_config_alloc()</code></a>) +can be passed this way.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_listener_set_size()</code></dt> +<dd> +<p>This function is used to configure a size, <em>z</em>, typically for buffer sizes, +message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_set_string()</code></dt> +<dd> +<p>This function is used to pass configure a string, <em>str</em>. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a <code>NUL</code> (<code>\0</code>) byte. +(Other constraints may apply as well, see the documentation for each option +for details.)</p> +</dd> +<dt class="hdlist1"><code>nng_listener_set_uint64()</code></dt> +<dd> +<p>This function is used to configure a 64-bit unsigned value, <em>u64</em>. +This is typically used for options related to identifiers, network numbers, +and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>l</em> does not refer to an open listener.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The value being passed is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EREADONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is read-only.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The listener <em>l</em> is already started.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_listen.3.html">nng_listen(3)</a>, +<a href="nng_listener_create.3.html">nng_listener_create(3)</a> +<a href="nng_listener_get.3.html">nng_listener_get(3)</a> +<a href="nng_socket_set.3.html">nng_socket_set(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_listener_setopt.3.html b/man/v1.7.2/nng_listener_setopt.3.html new file mode 100644 index 00000000..97793f87 --- /dev/null +++ b/man/v1.7.2/nng_listener_setopt.3.html @@ -0,0 +1,256 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_listener_setopt(3) +--- +<h1>nng_listener_setopt(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_listener_setopt - set listener option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_setopt</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">valsz</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_setopt_bool</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">bval</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_setopt_int</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">ival</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_setopt_ms</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">dur</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_setopt_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_setopt_size</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">z</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_setopt_string</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">str</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_setopt_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">u64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +These functions are deprecated. Please see <a href="nng_listener_set.3.html">nng_listener_set</a>. +They may not be present if the library was built with <code>NNG_ELIDE_DEPRECATED</code>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p> +The <code>nng_listener_setopt()</code> functions are used to configure options for +the <a href="nng_listener.5.html">listener</a> <em>l</em>. +The actual options that may be configured in this way +vary, and many are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally some transport-specific options +are documented with the transports themselves.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Once a listener has started, it is generally not possible to change +its configuration. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is configured on the listener <em>l</em>.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_listener_setopt()</code></dt> +<dd> +<p>This function is untyped, and can be used to configure any arbitrary data. +The <em>val</em> pointer addresses the data to copy, and <em>valsz</em> is the +size of the objected located at <em>val</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_setopt_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The <em>bval</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_setopt_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The <em>ival</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_setopt_ms()</code></dt> +<dd> +<p>This function is used to configure time durations (such as timeouts) using +type <a href="nng_duration.5.html"><code>nng_duration</code></a>. +The duration <em>dur</em> is an integer number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_setopt_ptr()</code></dt> +<dd> +<p>This function is used to pass a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed by other functions. +For example, TLS configuration objects created with +(<a href="nng_tls_config_alloc.3tls.html"><code>nng_tls_config_alloc()</code></a>) +can be passed this way.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_listener_setopt_size()</code></dt> +<dd> +<p>This function is used to configure a size, <em>z</em>, typically for buffer sizes, +message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_listener_setopt_string()</code></dt> +<dd> +<p>This function is used to pass configure a string, <em>str</em>. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a <code>NUL</code> (<code>\0</code>) byte. +(Other constraints may apply as well, see the documentation for each option +for details.)</p> +</dd> +<dt class="hdlist1"><code>nng_listener_setopt_uint64()</code></dt> +<dd> +<p>This function is used to configure a 64-bit unsigned value, <em>u64</em>. +This is typically used for options related to identifiers, network numbers, +and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>l</em> does not refer to an open listener.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The value being passed is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EREADONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is read-only.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The listener <em>l</em> is already started.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_listen.3.html">nng_listen(3)</a>, +<a href="nng_listener_create.3.html">nng_listener_create(3)</a> +<a href="nng_listener_getopt.3.html">nng_listener_getopt(3)</a> +<a href="nng_setopt.3.html">nng_setopt(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_listener_start.3.html b/man/v1.7.2/nng_listener_start.3.html new file mode 100644 index 00000000..94ac668e --- /dev/null +++ b/man/v1.7.2/nng_listener_start.3.html @@ -0,0 +1,93 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_listener_start(3) +--- +<h1>nng_listener_start(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_listener_start - start listener</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_listener_start</span><span class="tok-p">(</span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_listener_start()</code> function starts the listener <em>l</em>.</p> +</div> +<div class="paragraph"> +<p>This causes the listener to bind to the address it was created with, +and to start accepting connections from remote +dialers. +Each new connection results in an <a href="nng_pipe.5.html"><code>nng_pipe</code></a> object, +which will be attached to the listener’s socket.</p> +</div> +<div class="paragraph"> +<p>The <em>flags</em> argument is ignored, but reserved for future use.</p> +</div> +<div class="paragraph"> +<p>Once a listener has started, it is generally not possible to change +its configuration.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>l</em> does not refer to an open listener.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The listener <em>l</em> is already started.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_listen.3.html">nng_listen(3)</a>, +<a href="nng_listener_create.3.html">nng_listener_create(3)</a> +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg.5.html b/man/v1.7.2/nng_msg.5.html new file mode 100644 index 00000000..6a661d72 --- /dev/null +++ b/man/v1.7.2/nng_msg.5.html @@ -0,0 +1,86 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg(5) +--- +<h1>nng_msg(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg - message</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_msg</span><span class="tok-w"> </span><span class="tok-n">nng_msg</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>An <code>nng_msg</code> represents a single message sent between Scalability Protocols +peers. +Messages internally have a body, containing the application supplied +payload, and a header, containing protocol specific routing and similar +related information.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Using message-oriented functions is a good way to reduce the likelihood +of data copies and improve application performance. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Messages are allocated using the <a href="nng_msg_alloc.3.html"><code>nng_msg_alloc()</code></a> +function, and are deallocated using the <a href="nng_msg_free.3.html"><code>nng_msg_free()</code></a> +function.</p> +</div> +<div class="paragraph"> +<p>In addition there are other functions used to access message contents, +including adding data to either the beginning or end of the message, +automatic data conversion, and removing data from the beginning or end. +These functions are designed to try to avoid copying message contents +by making use of scratch areas at the beginning and end of the message.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_get_msg.3.html">nng_aio_get_msg(3)</a>, +<a href="nng_aio_set_msg.3.html">nng_aio_set_msg(3)</a>, +<a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_body.3.html">nng_msg_body(3)</a>, +<a href="nng_msg_dup.3.html">nng_msg_dup(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_msg_header.3.html">nng_msg_header(3)</a>, +<a href="nng_msg_header_len.3.html">nng_msg_header_len(3)</a>, +<a href="nng_msg_len.3.html">nng_msg_len(3)</a>, +<a href="nng_msg_capacity.3.html">nng_msg_capacity(3)</a>, +<a href="nng_msg_reserve.3.html">nng_msg_reserve(3)</a>, +<a href="nng_msg_realloc.3.html">nng_msg_realloc(3)</a>, +<a href="nng_recvmsg.3.html">nng_recvmsg(3)</a>, +<a href="nng_sendmsg.3.html">nng_sendmsg(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_alloc.3.html b/man/v1.7.2/nng_msg_alloc.3.html new file mode 100644 index 00000000..3bd38748 --- /dev/null +++ b/man/v1.7.2/nng_msg_alloc.3.html @@ -0,0 +1,81 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_alloc(3) +--- +<h1>nng_msg_alloc(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_alloc - allocate a message</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">msgp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_alloc()</code> function allocates a new message with body length <em>size</em> +and stores the result in <em>msgp</em>. +Messages allocated with this function contain a body and optionally a header. +They are used with receive and transmit functions.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists to allocate a message.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_msg_body.3.html">nng_msg_body(3)</a>, +<a href="nng_msg_dup.3.html">nng_msg_dup(3)</a>, +<a href="nng_msg_header.3.html">nng_msg_header(3)</a>, +<a href="nng_msg_header_len.3.html">nng_msg_header_len(3)</a>, +<a href="nng_msg_len.3.html">nng_msg_len(3)</a>, +<a href="nng_msg_capacity.3.html">nng_msg_capacity(3)</a>, +<a href="nng_msg_reserve.3.html">nng_msg_reserve(3)</a>, +<a href="nng_msg_realloc.3.html">nng_msg_realloc(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_append.3.html b/man/v1.7.2/nng_msg_append.3.html new file mode 100644 index 00000000..026e7054 --- /dev/null +++ b/man/v1.7.2/nng_msg_append.3.html @@ -0,0 +1,84 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_append(3) +--- +<h1>nng_msg_append(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_append - append to message body</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_append</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_append_u16</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">val16</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_append_u32</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint32_t</span><span class="tok-w"> </span><span class="tok-n">val32</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_append_u64</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">val64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_append()</code> family of functions appends data to +the end of the body of message <em>msg</em>, reallocating it if necessary. +The first function appends <em>size</em> bytes, copying them from <em>val</em>. +The remaining functions append the value specified (such as <em>val32</em>) in +network-byte order (big-endian).</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_body.3.html">nng_msg_body(3)</a>, +<a href="nng_msg_chop.3.html">nng_msg_chop(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_msg_insert.3.html">nng_msg_insert(3)</a>, +<a href="nng_msg_len.3.html">nng_msg_len(3)</a>, +<a href="nng_msg_realloc.3.html">nng_msg_realloc(3)</a>, +<a href="nng_msg_trim.3.html">nng_msg_trim(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_body.3.html b/man/v1.7.2/nng_msg_body.3.html new file mode 100644 index 00000000..7f944ded --- /dev/null +++ b/man/v1.7.2/nng_msg_body.3.html @@ -0,0 +1,90 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_body(3) +--- +<h1>nng_msg_body(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_body - return message body</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_msg_body</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_body()</code> function returns a pointer to the start of the body +content of the message <em>msg</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The value returned by this is invalidated by a call to any of the +functions that modify the message itself. +Such functions are +<a href="nng_msg_free.3.html"><code>nng_msg_free()</code></a>, +<a href="nng_msg_realloc.3.html"><code>nng_msg_realloc()</code></a>, +any of the <a href="nng_msg_trim.3.html"><code>nng_msg_trim()</code></a>, +<a href="nng_msg_chop.3.html"><code>nng_msg_chop()</code></a>, +<a href="nng_msg_append.3.html"><code>nng_msg_append()</code></a>, +or <a href="nng_msg_insert.3.html"><code>nng_msg_insert()</code></a> variants. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Pointer to start of message body.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_append.3.html">nng_msg_append(3)</a>, +<a href="nng_msg_chop.3.html">nng_msg_chop(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_msg_insert.3.html">nng_msg_insert(3)</a>, +<a href="nng_msg_len.3.html">nng_msg_len(3)</a>, +<a href="nng_msg_capacity.3.html">nng_msg_capacity(3)</a>, +<a href="nng_msg_reserve.3.html">nng_msg_reserve(3)</a>, +<a href="nng_msg_realloc.3.html">nng_msg_realloc(3)</a>, +<a href="nng_msg_trim.3.html">nng_msg_trim(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_capacity.3.html b/man/v1.7.2/nng_msg_capacity.3.html new file mode 100644 index 00000000..1e99e763 --- /dev/null +++ b/man/v1.7.2/nng_msg_capacity.3.html @@ -0,0 +1,64 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_capacity(3) +--- +<h1>nng_msg_capacity(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_capacity - return message body length</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_capacity</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_capacity()</code> returns the storage allocated for the body of message <em>msg</em>. +The capacity includes the current contents of the message and free space after it. +The message body may grow to capacity without performing any further allocations.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Allocated capacity for message body.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_reserve.3.html">nng_msg_reserve(3)</a>, +<a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_body.3.html">nng_msg_body(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_chop.3.html b/man/v1.7.2/nng_msg_chop.3.html new file mode 100644 index 00000000..b7190329 --- /dev/null +++ b/man/v1.7.2/nng_msg_chop.3.html @@ -0,0 +1,87 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_chop(3) +--- +<h1>nng_msg_chop(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_chop - remove data from end of message body</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_chop</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_chop_u16</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val16</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_chop_u32</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint32_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val32</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_chop_u64</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_chop()</code> family of functions removes data from +the end of the body of message <em>msg</em>. +The first function removes <em>size</em> bytes. +The remaining functions remove 2, 4, or 8 bytes, and stores them in the value +(such as <em>val32</em>), +after converting them from network-byte order (big-endian) to native byte order.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The message body is too short to remove the requested data.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_append.3.html">nng_msg_append(3)</a>, +<a href="nng_msg_body.3.html">nng_msg_body(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_msg_insert.3.html">nng_msg_insert(3)</a>, +<a href="nng_msg_len.3.html">nng_msg_len(3)</a>, +<a href="nng_msg_capacity.3.html">nng_msg_capacity(3)</a>, +<a href="nng_msg_reserve.3.html">nng_msg_reserve(3)</a>, +<a href="nng_msg_realloc.3.html">nng_msg_realloc(3)</a>, +<a href="nng_msg_trim.3.html">nng_msg_trim(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_clear.3.html b/man/v1.7.2/nng_msg_clear.3.html new file mode 100644 index 00000000..f8af373f --- /dev/null +++ b/man/v1.7.2/nng_msg_clear.3.html @@ -0,0 +1,59 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_clear(3) +--- +<h1>nng_msg_clear(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_clear - clear message body content</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_clear</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_clear()</code> function resets the body length of <em>msg</em> to zero.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_dup.3.html b/man/v1.7.2/nng_msg_dup.3.html new file mode 100644 index 00000000..b54045d2 --- /dev/null +++ b/man/v1.7.2/nng_msg_dup.3.html @@ -0,0 +1,75 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_dup(3) +--- +<h1>nng_msg_dup(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_dup - duplicate a message</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_dup</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">dup</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_msg_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">orig</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_dup()</code> makes a duplicate of the original message <em>orig</em>, and +saves the result in the location pointed by <em>dup</em>. +The actual message body and header content is copied, +but the duplicate may contain a +different amount of unused space than the original message.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists to duplicate a message.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_free.3.html b/man/v1.7.2/nng_msg_free.3.html new file mode 100644 index 00000000..c2956231 --- /dev/null +++ b/man/v1.7.2/nng_msg_free.3.html @@ -0,0 +1,61 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_free(3) +--- +<h1>nng_msg_free(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_free - free a message</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_free</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_free()</code> function deallocates the message <em>msg</em> entirely.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_realloc.3.html">nng_msg_realloc(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_get_pipe.3.html b/man/v1.7.2/nng_msg_get_pipe.3.html new file mode 100644 index 00000000..67ec0372 --- /dev/null +++ b/man/v1.7.2/nng_msg_get_pipe.3.html @@ -0,0 +1,88 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_get_pipe(3) +--- +<h1>nng_msg_get_pipe(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_get_pipe - get pipe for message</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_get_pipe</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_get_pipe()</code> returns the <a href="nng_pipe.5.html"><code>nng_pipe</code></a> object +associated with message <em>msg</em>. +On receive, this is the pipe from which a message was received. +On transmit, this would be the pipe that the message should be delivered +to, if a specific peer is required.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Not all protocols support overriding the destination pipe. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The most usual use case for this is to obtain information about the peer +from which the message was received. +This can be used to provide different behaviors for different peers, such as +a higher level of authentication for peers located on an untrusted network. +The <a href="nng_pipe_getopt.3.html"><code>nng_pipe_getopt()</code></a> function +is useful in this situation.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the pipe associated with this message, which will +be a positive value. +If the pipe is non-positive, then that indicates that +no specific pipe is associated with the message.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_set_pipe.3.html">nng_msg_set_pipe(3)</a>, +<a href="nng_pipe_getopt.3.html">nng_pipe_getopt(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_header.3.html b/man/v1.7.2/nng_msg_header.3.html new file mode 100644 index 00000000..a4a905f7 --- /dev/null +++ b/man/v1.7.2/nng_msg_header.3.html @@ -0,0 +1,96 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_header(3) +--- +<h1>nng_msg_header(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_header - return message header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_msg_header</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_header()</code> function returns a pointer to the start of the header +content of the message <em>msg</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The message header contains protocol-specific header content. Most +applications should not need to access this content, but it is available +for raw mode sockets (set with the +<a href="nng_options.5.html#NNG_OPT_RAW"><code>NNG_OPT_RAW</code></a> option.) +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The value returned by this is invalidated by a call to any of the +functions that modify the message or the header content. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Pointer to start of message header.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_body.3.html">nng_msg_body(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_msg_header_append.3.html">nng_msg_header_append(3)</a>, +<a href="nng_msg_header_chop.3.html">nng_msg_header_chop(3)</a>, +<a href="nng_msg_header_insert.3.html">nng_msg_header_insert(3)</a> +<a href="nng_msg_header_len.3.html">nng_msg_header_len(3)</a>, +<a href="nng_msg_header_trim.3.html">nng_msg_header_trim(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_header_append.3.html b/man/v1.7.2/nng_msg_header_append.3.html new file mode 100644 index 00000000..3606bf1e --- /dev/null +++ b/man/v1.7.2/nng_msg_header_append.3.html @@ -0,0 +1,84 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_header_append(3) +--- +<h1>nng_msg_header_append(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_header_append - append to message header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_append</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_append_u16</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">val16</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_append_u32</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint32_t</span><span class="tok-w"> </span><span class="tok-n">val32</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_append_u64</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">val64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_header_append()</code> family of functions appends data to +the end of the headers of message <em>msg</em>, reallocating it if necessary. +The first function appends <em>size</em> bytes, copying them from <em>val</em>.</p> +</div> +<div class="paragraph"> +<p>The remaining functions append the value (such as <em>val32</em>) in +network-byte order (big-endian).</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_header.3.html">nng_msg_header(3)</a>, +<a href="nng_msg_header_chop.3.html">nng_msg_header_chop(3)</a>, +<a href="nng_msg_header_insert.3.html">nng_msg_header_insert(3)</a>, +<a href="nng_msg_header_len.3.html">nng_msg_header_len(3)</a>, +<a href="nng_msg_header_trim.3.html">nng_msg_header_trim(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_header_chop.3.html b/man/v1.7.2/nng_msg_header_chop.3.html new file mode 100644 index 00000000..c895381e --- /dev/null +++ b/man/v1.7.2/nng_msg_header_chop.3.html @@ -0,0 +1,84 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_header_chop(3) +--- +<h1>nng_msg_header_chop(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_header_chop - remove data from end of message header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_chop</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_chop_u16</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val16</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_chop_u32</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint32_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val32</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_chop_u64</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_header_chop()</code> family of functions removes +data from the end of the header of message <em>msg</em>. +The first function removes <em>size</em> bytes. +The remaining functions remove 2, 4, or 8 bytes, and stores them in the value +(such as <em>val32</em>), +after converting them from network-byte order (big-endian) to native +byte order.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These function return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The message header is too short to remove the requested data.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_header.3.html">nng_msg_header(3)</a>, +<a href="nng_msg_header_append.3.html">nng_msg_header_append(3)</a>, +<a href="nng_msg_header_insert.3.html">nng_msg_header_insert(3)</a>, +<a href="nng_msg_header_len.3.html">nng_msg_header_len(3)</a>, +<a href="nng_msg_header_trim.3.html">nng_msg_header_trim(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_header_clear.3.html b/man/v1.7.2/nng_msg_header_clear.3.html new file mode 100644 index 00000000..6c7f2df9 --- /dev/null +++ b/man/v1.7.2/nng_msg_header_clear.3.html @@ -0,0 +1,60 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_header_clear(3) +--- +<h1>nng_msg_header_clear(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_header_clear - clear message header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_clear</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_clear()</code> function resets the header length of <em>msg</em> to zero.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_header_insert.3.html b/man/v1.7.2/nng_msg_header_insert.3.html new file mode 100644 index 00000000..a10b69d7 --- /dev/null +++ b/man/v1.7.2/nng_msg_header_insert.3.html @@ -0,0 +1,86 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_header_insert(3) +--- +<h1>nng_msg_header_insert(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_header_insert - prepend to message header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_insert</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_insert_u16</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">val16</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_insert_u32</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint32_t</span><span class="tok-w"> </span><span class="tok-n">val32</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_insert_u64</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">val64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_header_insert()</code> family of functions +prepends data to the front of the headers of message <em>msg</em>, reallocating +if necessary. +The first function prepends <em>size</em> bytes, copying them from <em>val</em>. +The remaining functions prepend the specified value (such as <em>val32</em>) in +network-byte order (big-endian).</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_header.3.html">nng_msg_header(3)</a>, +<a href="nng_msg_header_append.3.html">nng_msg_header_append(3)</a>, +<a href="nng_msg_header_chop.3.html">nng_msg_header_chop(3)</a>, +<a href="nng_msg_header_len.3.html">nng_msg_header_len(3)</a>, +<a href="nng_msg_header_trim.3.html">nng_msg_header_trim(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_msg_capacity.3.html">nng_msg_capacity(3)</a>, +<a href="nng_msg_reserve.3.html">nng_msg_reserve(3)</a>, +<a href="nng_msg_realloc.3.html">nng_msg_realloc(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_header_len.3.html b/man/v1.7.2/nng_msg_header_len.3.html new file mode 100644 index 00000000..0b430bf1 --- /dev/null +++ b/man/v1.7.2/nng_msg_header_len.3.html @@ -0,0 +1,61 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_header_len(3) +--- +<h1>nng_msg_header_len(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_header_len - return message header length</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_len</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_header_len()</code> returns the length of message header of <em>msg</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Length of message header.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_header.3.html">nng_msg_header(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_header_trim.3.html b/man/v1.7.2/nng_msg_header_trim.3.html new file mode 100644 index 00000000..bf9ed06e --- /dev/null +++ b/man/v1.7.2/nng_msg_header_trim.3.html @@ -0,0 +1,85 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_header_trim(3) +--- +<h1>nng_msg_header_trim(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_header_trim - remove data from start of message header</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_trim</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_trim_u16</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val16</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_trim_u32</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint32_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val32</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_header_trim_u64</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_header_trim()</code> family of functions remove +data from the start of the header of message <em>msg</em>. +The first function removes <em>size</em> bytes. +The remaining functions removes 2, 4, or 8 bytes, and stores them in the +value (such as <em>val32</em>), +after converting them from network-byte order (big-endian) to native +byte order.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The message header is too short to remove the requested data.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_header.3.html">nng_msg_header(3)</a>, +<a href="nng_msg_header_append.3.html">nng_msg_header_append(3)</a>, +<a href="nng_msg_header_chop.3.html">nng_msg_header_chop(3)</a>, +<a href="nng_msg_header_insert.3.html">nng_msg_header_insert(3)</a>, +<a href="nng_msg_header_len.3.html">nng_msg_header_len(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_insert.3.html b/man/v1.7.2/nng_msg_insert.3.html new file mode 100644 index 00000000..3089a201 --- /dev/null +++ b/man/v1.7.2/nng_msg_insert.3.html @@ -0,0 +1,99 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_insert(3) +--- +<h1>nng_msg_insert(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_insert - prepend to message body</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_insert</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_insert_u16</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">val16</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_insert_u32</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint32_t</span><span class="tok-w"> </span><span class="tok-n">val32</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_insert_u64</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">val64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_insert()</code> family of functions prepends data to +the front of the body of message <em>msg</em>, reallocating it if necessary. +The first function prepends <em>size</em> bytes, copying them from <em>val</em>. +The remaining functions prepend the specified value (such as <em>val32</em>) +in network-byte order (big-endian).</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +These functions make use of space pre-allocated in front of the +message body if available, so they can often avoid performing any reallocation. +Applications should use these instead of reallocating and copying message +content themselves, in order to benefit from this capability. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_append.3.html">nng_msg_append(3)</a>, +<a href="nng_msg_body.3.html">nng_msg_body(3)</a>, +<a href="nng_msg_chop.3.html">nng_msg_chop(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_msg_len.3.html">nng_msg_len(3)</a>, +<a href="nng_msg_realloc.3.html">nng_msg_realloc(3)</a>, +<a href="nng_msg_trim.3.html">nng_msg_trim(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_len.3.html b/man/v1.7.2/nng_msg_len.3.html new file mode 100644 index 00000000..44972459 --- /dev/null +++ b/man/v1.7.2/nng_msg_len.3.html @@ -0,0 +1,61 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_len(3) +--- +<h1>nng_msg_len(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_len - return message body length</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_len</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_len()</code> returns the length of the body of message <em>msg</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Length of message body.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_body.3.html">nng_msg_body(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_realloc.3.html b/man/v1.7.2/nng_msg_realloc.3.html new file mode 100644 index 00000000..34377767 --- /dev/null +++ b/man/v1.7.2/nng_msg_realloc.3.html @@ -0,0 +1,112 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_realloc(3) +--- +<h1>nng_msg_realloc(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_realloc - reallocate a message</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_realloc</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_realloc()</code> function re-allocates a message so that it has +a body of length <em>size</em>. +This message attempts to avoid extra allocations, +and will reuse the existing memory when possible.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +<code>nng_msg_realloc</code> is suitable for creating space for direct writing of data. +When appending many small pieces of data to a message using <a href="nng_msg_append.3.html"><code>nng_msg_append()</code></a>, +allocations may be reduced by first using <a href="nng_msg_reserve.3.html"><code>nng_msg_reserve()</code></a> +to create sufficient space. +In any case, reallocating or appending to a message is guaranteed to succeed if the resulting +body length is less than <a href="nng_msg_capacity.3.html"><code>nng_msg_capacity()</code></a>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Pointers to message body and header content obtained prior to this +function must not be in use, as the underlying memory used for the message +may have changed, particularly if the message size is increasing. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists to reallocate a message.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_reserve.3.html">nng_msg_reserve(3)</a>, +<a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_append.3.html">nng_msg_append(3)</a>, +<a href="nng_msg_body.3.html">nng_msg_body(3)</a>, +<a href="nng_msg_chop.3.html">nng_msg_chop(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_msg_insert.3.html">nng_msg_insert(3)</a>, +<a href="nng_msg_len.3.html">nng_msg_len(3)</a>, +<a href="nng_msg_trim.3.html">nng_msg_trim(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_reserve.3.html b/man/v1.7.2/nng_msg_reserve.3.html new file mode 100644 index 00000000..6e1187be --- /dev/null +++ b/man/v1.7.2/nng_msg_reserve.3.html @@ -0,0 +1,109 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_reserve(3) +--- +<h1>nng_msg_reserve(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_reserve - reserve storage for a message</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_reserve</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">capacity</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_reserve()</code> function ensures a message has allocated enough storage +to accommodate a body of the given length. +This message attempts to avoid extra allocations, +and will reuse the existing memory when possible.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Using this message before <a href="nng_msg_append.3.html"><code>nng_msg_append()</code></a> +will prevent additional memory allocations until the message’s length exceeds +the alotted capacity. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Pointers to message body and header content obtained prior to this +function must not be in use, as the underlying memory used for the message +may have changed, particularly if the message capacity is increasing. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists to reallocate a message.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_capacity.3.html">nng_msg_capacity(3)</a>, +<a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_append.3.html">nng_msg_append(3)</a>, +<a href="nng_msg_body.3.html">nng_msg_body(3)</a>, +<a href="nng_msg_chop.3.html">nng_msg_chop(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_msg_insert.3.html">nng_msg_insert(3)</a>, +<a href="nng_msg_len.3.html">nng_msg_len(3)</a>, +<a href="nng_msg_trim.3.html">nng_msg_trim(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_set_pipe.3.html b/man/v1.7.2/nng_msg_set_pipe.3.html new file mode 100644 index 00000000..cb65b5dd --- /dev/null +++ b/man/v1.7.2/nng_msg_set_pipe.3.html @@ -0,0 +1,78 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_set_pipe(3) +--- +<h1>nng_msg_set_pipe(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_set_pipe - set pipe for message</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_set_pipe</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_set_pipe()</code> sets the pipe associated with message <em>m</em> to <em>p</em>. +This is most often useful when used with protocols that support directing +a message to a specific peer. +For example the <a href="nng_pair.7.html"><em>pair</em></a> version 1 protocol can do +this when <code>NNG_OPT_PAIR1_POLY</code> mode is set.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Not all protocols support overriding the destination pipe. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_get_pipe.3.html">nng_msg_get_pipe(3)</a>, +<a href="nng_pipe_getopt.3.html">nng_pipe_getopt(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msg_trim.3.html b/man/v1.7.2/nng_msg_trim.3.html new file mode 100644 index 00000000..193d96c5 --- /dev/null +++ b/man/v1.7.2/nng_msg_trim.3.html @@ -0,0 +1,86 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msg_trim(3) +--- +<h1>nng_msg_trim(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msg_trim - remove data from start of message body</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_trim</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_trim_u16</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val16</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_trim_u32</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint32_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val32</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_msg_trim_u64</span><span class="tok-p">(</span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msg_trim()</code> family of functions removes data from +the start of the body of message <em>msg</em>. +The first function removes <em>size</em> bytes. +The remaining functions remove 2, 4, or 8 bytes, and stores them in the value +(such as <em>val32</em>), +after converting them from network-byte order (big-endian) to native +byte order.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The message body is too short to remove the requested data.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_msg_append.3.html">nng_msg_append(3)</a>, +<a href="nng_msg_body.3.html">nng_msg_body(3)</a>, +<a href="nng_msg_chop.3.html">nng_msg_chop(3)</a>, +<a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_msg_insert.3.html">nng_msg_insert(3)</a>, +<a href="nng_msg_len.3.html">nng_msg_len(3)</a>, +<a href="nng_msg_realloc.3.html">nng_msg_realloc(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_msleep.3supp.html b/man/v1.7.2/nng_msleep.3supp.html new file mode 100644 index 00000000..fdd357b5 --- /dev/null +++ b/man/v1.7.2/nng_msleep.3supp.html @@ -0,0 +1,77 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_msleep(3supp) +--- +<h1>nng_msleep(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_msleep - sleep milliseconds</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_msleep</span><span class="tok-p">(</span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">msec</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_msleep()</code> blocks the caller for at least <em>msec</em> milliseconds.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function may block for longer than requested. +The actual wait time is determined by the capabilities of the +underlying system. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sleep_aio.3.html">nng_sleep_aio(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_clock.3supp.html">nng_clock(3supp)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_mtx_alloc.3supp.html b/man/v1.7.2/nng_mtx_alloc.3supp.html new file mode 100644 index 00000000..a44ce3f0 --- /dev/null +++ b/man/v1.7.2/nng_mtx_alloc.3supp.html @@ -0,0 +1,87 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_mtx_alloc(3supp) +--- +<h1>nng_mtx_alloc(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_mtx_alloc - allocate mutex</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_mtx</span><span class="tok-w"> </span><span class="tok-n">nng_mtx</span><span class="tok-p">;</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_mtx_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_mtx</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">mtxp</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_mtx_alloc()</code> function allocates mutex and returns it in <em>mtxp</em>.</p> +</div> +<div class="paragraph"> +<p>The mutex objects created by this function are suitable only for +simple lock and unlock operations, and are not recursive. +Every effort has been made to use light-weight underlying primitives when available.</p> +</div> +<div class="paragraph"> +<p>Mutex (mutual exclusion) objects can be thought of as binary semaphores, +where only a single thread of execution is permitted to acquire the semaphore.</p> +</div> +<div class="paragraph"> +<p>Furthermore, a mutex can only be unlocked by the thread that locked it.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_cv_alloc.3supp.html">nng_cv_alloc(3supp)</a>, +<a href="nng_mtx_free.3supp.html">nng_mtx_free(3supp)</a>, +<a href="nng_mtx_lock.3supp.html">nng_mtx_lock(3supp)</a>, +<a href="nng_mtx_unlock.3supp.html">nng_mtx_unlock(3supp)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_mtx_free.3supp.html b/man/v1.7.2/nng_mtx_free.3supp.html new file mode 100644 index 00000000..c1f7768b --- /dev/null +++ b/man/v1.7.2/nng_mtx_free.3supp.html @@ -0,0 +1,61 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_mtx_free(3supp) +--- +<h1>nng_mtx_free(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_mtx_free - free mutex</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_mtx_free</span><span class="tok-p">(</span><span class="tok-n">nng_mtx</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">mtx</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_mtx_free()</code> function frees the mutex <em>mtx</em>. +The mutex must not be locked when this function is called.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_mtx_alloc.3supp.html">nng_mtx_alloc(3supp)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_mtx_lock.3supp.html b/man/v1.7.2/nng_mtx_lock.3supp.html new file mode 100644 index 00000000..fe72ad10 --- /dev/null +++ b/man/v1.7.2/nng_mtx_lock.3supp.html @@ -0,0 +1,107 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_mtx_lock(3supp) +--- +<h1>nng_mtx_lock(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_mtx_lock - lock mutex</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_mtx_lock</span><span class="tok-p">(</span><span class="tok-n">nng_mtx</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">mtx</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_mtx_lock()</code> acquires exclusive ownership of the mutex <em>mtx</em>. +If the lock is already owned, this function will wait until the current +owner releases it with <a href="nng_mtx_unlock.3supp.html"><code>nng_mtx_unlock()</code></a>.</p> +</div> +<div class="paragraph"> +<p>If multiple threads are waiting for the lock, the order of acquisition +is not specified.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +A mutex can <em>only</em> be unlocked by the thread that locked it. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Mutex locks are <em>not</em> recursive; attempts to reacquire the +same mutex may result in deadlock or aborting the current program. +It is a programming error for the owner of a mutex to attempt to +reacquire it. +</td> +</tr> +</table> +</div> +<div class="sidebarblock"> +<div class="content"> +<div class="paragraph"> +<p><em>NNG</em> offers neither a non-blocking variant that can fail, +nor recursive mutexes. +This is by design, as <em>NNG</em> itself does not use such things, +and most often the need for them is the result of poor design. +If such capabilities are needed, they may be synthesized fairly +easily from mutexes and condition variables.</p> +</div> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_cv_alloc.3supp.html">nng_cv_alloc(3supp)</a>, +<a href="nng_mtx_alloc.3supp.html">nng_mtx_alloc(3supp)</a>, +<a href="nng_mtx_unlock.3supp.html">nng_mtx_unlock(3supp)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_mtx_unlock.3supp.html b/man/v1.7.2/nng_mtx_unlock.3supp.html new file mode 100644 index 00000000..01f13206 --- /dev/null +++ b/man/v1.7.2/nng_mtx_unlock.3supp.html @@ -0,0 +1,76 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_mtx_unlock(3supp) +--- +<h1>nng_mtx_unlock(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_mtx_unlock - unlock mutex</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_mtx_unlock</span><span class="tok-p">(</span><span class="tok-n">nng_mtx</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">mtx</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_mtx_unlock()</code> relinquishes ownership of the mutex <em>mtx</em> that +was previously acquired via <a href="nng_mtx_lock.3supp.html"><code>nng_mtx_lock()</code></a>.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +A mutex can <em>only</em> be unlocked by the thread that locked it. +Attempting to unlock a mutex that is not owned by the caller will result +in undefined behavior. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_mtx_alloc.3supp.html">nng_mtx_alloc(3supp)</a>, +<a href="nng_mtx_lock.3supp.html">nng_mtx_lock(3supp)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_options.5.html b/man/v1.7.2/nng_options.5.html new file mode 100644 index 00000000..bf0d4fac --- /dev/null +++ b/man/v1.7.2/nng_options.5.html @@ -0,0 +1,644 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_options(5) +--- +<h1>nng_options(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_options - socket, dialer, listener, and pipe options</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-cp">#define NNG_OPT_SOCKNAME "socket-name"</span> +<span class="tok-cp">#define NNG_OPT_RAW "raw"</span> +<span class="tok-cp">#define NNG_OPT_PROTO "protocol"</span> +<span class="tok-cp">#define NNG_OPT_PROTONAME "protocol-name"</span> +<span class="tok-cp">#define NNG_OPT_PEER "peer"</span> +<span class="tok-cp">#define NNG_OPT_PEERNAME "peer-name"</span> +<span class="tok-cp">#define NNG_OPT_RECVBUF "recv-buffer"</span> +<span class="tok-cp">#define NNG_OPT_SENDBUF "send-buffer"</span> +<span class="tok-cp">#define NNG_OPT_RECVFD "recv-fd"</span> +<span class="tok-cp">#define NNG_OPT_SENDFD "send-fd"</span> +<span class="tok-cp">#define NNG_OPT_RECVTIMEO "recv-timeout"</span> +<span class="tok-cp">#define NNG_OPT_SENDTIMEO "send-timeout"</span> +<span class="tok-cp">#define NNG_OPT_LOCADDR "local-address"</span> +<span class="tok-cp">#define NNG_OPT_REMADDR "remote-address"</span> +<span class="tok-cp">#define NNG_OPT_URL "url"</span> +<span class="tok-cp">#define NNG_OPT_MAXTTL "ttl-max"</span> +<span class="tok-cp">#define NNG_OPT_RECVMAXSZ "recv-size-max"</span> +<span class="tok-cp">#define NNG_OPT_RECONNMINT "reconnect-time-min"</span> +<span class="tok-cp">#define NNG_OPT_RECONNMAXT "reconnect-time-max"</span> +<span class="tok-cp">#define NNG_OPT_PEER_GID "ipc:peer-gid"</span> +<span class="tok-cp">#define NNG_OPT_PEER_PID "ipc:peer-pid"</span> +<span class="tok-cp">#define NNG_OPT_PEER_UID "ipc:peer-uid"</span> +<span class="tok-cp">#define NNG_OPT_PEER_ZONEID "ipc:peer-zoneid"</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This page documents the various standard options that can be set or +retrieved on objects.</p> +</div> +<div class="paragraph"> +<p>Sockets (<a href="nng_socket.5.html"><code>nng_socket</code></a> objects) use the functions +<a href="nng_socket_get.3.html"><code>nng_socket_get()</code></a> +and <a href="nng_socket_set.3.html"><code>nng_socket_set()</code></a> to set and retrieve option values.</p> +</div> +<div class="paragraph"> +<p>Dialers (<a href="nng_dialer.5.html"><code>nng_dialer</code></a> objects) use the functions +<a href="nng_dialer_get.3.html"><code>nng_dialer_get()</code></a> and +<a href="nng_dialer_set.3.html"><code>nng_dialer_set()</code></a> to set and retrieve option +values.</p> +</div> +<div class="paragraph"> +<p>Listeners (<a href="nng_listener.5.html"><code>nng_listener</code></a> objects) use the functions +<a href="nng_listener_get.3.html"><code>nng_listener_get()</code></a> +and <a href="nng_listener_set.3.html"><code>nng_listener_set()</code></a> to set and +retrieve option values.</p> +</div> +<div class="paragraph"> +<p>Pipes (<a href="nng_pipe.5.html"><code>nng_pipe</code></a> objects) can only retrieve option values using +the <a href="nng_pipe_get.3.html"><code>nng_pipe_get()</code></a> function.</p> +</div> +<div class="paragraph"> +<p>Other object types may have additional methods to access these options.</p> +</div> +<div class="paragraph"> +<p>In addition to the options listed here, transports and protocols will generally +have some of their own options, which will be documented with the transport +or protocol.</p> +</div> +<div class="sect2"> +<h3 id="_generic_options">Generic Options</h3> +<div class="paragraph"> +<p>In the following list of options, the name of the option is supplied, +along with the data type of the underlying value.</p> +</div> +<div class="paragraph"> +<p>Some options are only meaningful or supported in certain contexts; for +example there is no single meaningful address for a socket, since sockets +can have multiple dialers and endpoints associated with them. +An attempt has been made to include details about such restrictions in the +description of the option.</p> +</div> +<div id="NNG_OPT_LOCADDR" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_LOCADDR</code></dt> +<dd> +<p>(<a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a>) +This read-only option may be used on listeners, dialers and connected pipes, and +represents the local address used for communication. +NOTE: Not all transports support this option, and some transports may support it on +listeners but not dialers.</p> +<div class="paragraph"> +<p>When used on a TCP dialer, this option is used to configure the source IP +address that will be used when initiating outgoing connections. +The specific port number will be ignored, however, and the system will +choose a random ephemeral port instead.</p> +</div> +</dd> +</dl> +</div> +<div id="NNG_OPT_RAW" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_RAW</code></dt> +<dd> +<p> + +(<code>bool</code>) +This read-only option indicates whether the socket is in raw mode. +If <code>true</code>, the socket is in raw mode, and if <code>false</code> the socket is +in normal mode.</p> +<div class="paragraph"> +<p>Raw mode sockets generally do not have any protocol-specific semantics applied +to them; instead the application is expected to perform such semantics itself. +(For example, in normal mode a <a href="nng_rep.7.html"><em>rep</em></a> socket would +automatically copy message headers from a received message to the corresponding +reply, whereas in raw mode this is not done.) +See <a href="nng.7.html#raw_mode">Raw Mode</a> for more details.</p> +</div> +</dd> +</dl> +</div> +<div id="NNG_OPT_RECONNMINT" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_RECONNMINT</code></dt> +<dd> +<p> +(<a href="nng_duration.5.html"><code>nng_duration</code></a>) +This is the minimum amount of time (milliseconds) to wait before attempting +to establish a connection after a previous attempt has failed. +This can be set on a socket, but it can also be overridden on an individual +dialer. +The option is irrelevant for listeners.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_RECONNMAXT" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_RECONNMAXT</code></dt> +<dd> +<p> + +(<a href="nng_duration.5.html"><code>nng_duration</code></a>) +This is the maximum amount of time +(milliseconds) to wait before attempting to establish a connection after +a previous attempt has failed. +If this is non-zero, then the time between successive connection attempts +will start at the value of <code>NNG_OPT_RECONNMINT</code>, +and grow exponentially, until it reaches this value. +If this value is zero, then no exponential +back-off between connection attempts is done, and each attempt will wait +the time specified by <code>NNG_OPT_RECONNMINT</code>. +This can be set on a socket, but it can also be overridden on an individual +dialer. +The option is irrelevant for listeners.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_RECVBUF" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_RECVBUF</code></dt> +<dd> +<p> + +(<code>int</code>) +This is the depth of the socket’s receive buffer as a number of messages. +Messages received by a transport may be buffered until the application +has accepted them for delivery. +This value must be an integer between 0 and 8192, inclusive. +NOTE: Not all protocols support buffering received messages. +For example <a href="nng_req.7.html"><em>req</em></a> can only deal with a single reply at a time.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_RECVFD" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_RECVFD</code></dt> +<dd> +<p> + + +(<code>int</code>) +This read-only option is used to obtain an integer file descriptor suitable +for use with +<a href="http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html"><code>poll()</code></a>, +<a href="http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html"><code>select()</code></a>, +(or on Windows systems +<a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx"><code>WSAPoll()</code></a>) +and similar functions. +This descriptor will be <strong>readable</strong> when a message is available for receiving +on the socket. +When no message is ready for receiving, then this file descriptor will <strong>not</strong> +be readable.</p> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Applications should never attempt to read or write to the +returned file descriptor. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This option is incompatible with +<a href="nng_ctx.5.html"><code>nng_ctx</code></a> contexts and should not be used on a socket +where they are in use. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +While this option may help applications integrate into existing polling +loops, it is more efficient, and often easier, to use the asynchronous I/O +objects instead. +See <a href="nng_aio_alloc.3.html"><code>nng_aio_alloc()</code></a>. +</td> +</tr> +</table> +</div> +</dd> +</dl> +</div> +<div id="NNG_OPT_RECVMAXSZ" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_RECVMAXSZ</code></dt> +<dd> +<p> +(<code>size_t</code>) +This is the maximum message size that the will be accepted from a remote peer. +If a peer attempts to send a message larger than this, then the message +will be discarded. +If the value of this is zero, then no limit on message sizes is enforced. +This option exists to prevent certain kinds of denial-of-service attacks, +where a malicious agent can claim to want to send an extraordinarily +large message, without sending any data. +This option can be set for the socket, but may be overridden for on a +per-dialer or per-listener basis.</p> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Applications on hostile networks should set this to a non-zero +value to prevent denial-of-service attacks. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This option should be set before any listeners or dialers are added. +Ideally this option should be set on specific dialers or listeners; setting it +on the socket globally is deprecated behavior, and might not work in a future release, +or might only work for endpoints that have not yet been created. +(Maximum receive sizes might be negotiated during connection establishment for +future transports, which means that the option needs to be set before any connections +are established.) +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Some transports may have further message size restrictions. +</td> +</tr> +</table> +</div> +</dd> +</dl> +</div> +<div id="NNG_OPT_RECVTIMEO" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_RECVTIMEO</code></dt> +<dd> +<p> + +(<a href="nng_duration.5.html"><code>nng_duration</code></a>) +This is the socket receive timeout in milliseconds. +When no message is available for receiving at the socket for this period of +time, receive operations will fail with a return value of <code>NNG_ETIMEDOUT</code>.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_REMADDR" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_REMADDR</code></dt> +<dd> +<p>(<a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a>) +This read-only option may be used on dialers and connected pipes, and +represents the address of a remote peer. +Not all transports support this option.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_SENDBUF" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_SENDBUF</code></dt> +<dd> +<p> + +(<code>int</code>) +This is the depth of the socket send buffer as a number of messages. +Messages sent by an application may be buffered by the socket until a +transport is ready to accept them for delivery. +This value must be an integer between 0 and 8192, inclusive.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Not all protocols support buffering sent messages. +For example, <a href="nng_req.7.html"><em>req</em></a> can only have a single request +outstanding at a time (per context). +</td> +</tr> +</table> +</div> +</dd> +</dl> +</div> +<div id="NNG_OPT_SENDFD" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_SENDFD</code></dt> +<dd> +<p> + + +(<code>int</code>) +This read-only option is used to obtain an integer file descriptor suitable +for use with +<a href="http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html"><code>poll()</code></a>, +<a href="http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html"><code>select()</code></a>, +(or on Windows systems +<a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx"><code>WSAPoll()</code></a>) +and similar functions.</p> +<div class="paragraph"> +<p>This descriptor will be <strong>readable</strong> when the socket is able to accept a +message for sending without blocking. +When the socket is no longer able to accept such messages without blocking, +the descriptor will <strong>not</strong> be readable.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Applications should never attempt to read or write to the +returned file descriptor; use should be limited to polling system calls only. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This option is incompatible with +<a href="nng_ctx.5.html"><code>nng_ctx</code></a> contexts and should not be used on a socket +where they are in use. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +While this option may help applications integrate into existing polling +loops, it is more efficient, and often easier, to use the asynchronous I/O +objects instead. +See <a href="nng_aio_alloc.3.html"><code>nng_aio_alloc()</code></a>. +</td> +</tr> +</table> +</div> +</dd> +</dl> +</div> +<div id="NNG_OPT_SENDTIMEO" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_SENDTIMEO</code></dt> +<dd> +<p> + +(<a href="nng_duration.5.html"><code>nng_duration</code></a>) +This is the socket send timeout in milliseconds. +When a message cannot be queued for delivery by the socket for this period of +time (such as if send buffers are full), the operation will fail with a +return value of <code>NNG_ETIMEDOUT</code>.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_SOCKNAME" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_SOCKNAME</code></dt> +<dd> +<p> +(string) +This the socket name. +By default, this is a string corresponding to the value of the socket. +The string must fit within 64-bytes, including the terminating +<code>NUL</code> byte. +The value is intended for application use, and is not used for anything +in the library itself.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_MAXTTL" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_MAXTTL</code></dt> +<dd> +<p>(<code>int</code>) + +This is the maximum number of times a message may traverse across +a <a href="nng_device.3.html"><code>nng_device()</code></a> forwarders. +The intention here is to prevent forwarding loops in device chains. +When this is supported, it can have a value between 1 and 255, inclusive.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Not all protocols support this option. +Those that do generally have a default value of 8. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Each node along a forwarding path may have its own value for the +maximum time-to-live, and performs its own checks before forwarding a message. +Therefore it is helpful if all nodes in the topology use the same value for +this option. +</td> +</tr> +</table> +</div> +</dd> +</dl> +</div> +<div id="NNG_OPT_URL" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_URL</code></dt> +<dd> +<p> + +(string) +This read-only option is used to obtain the URL with which a listener +or dialer was configured. +Accordingly it can only be used with dialers, listeners, and pipes.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Some transports will canonify URLs before returning them to the +application. +</td> +</tr> +</table> +</div> +</dd> +</dl> +</div> +<div id="NNG_OPT_PROTO" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_PROTO</code></dt> +<dd> +<p>(<code>int</code>) +This read-only option is used to obtain the 16-bit number for the socket’s protocol.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_PEER" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_PEER</code></dt> +<dd> +<p>(<code>int</code>) +This read-only option is used to obtain the 16-bit number of the +peer protocol for the socket.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_PEER_GID" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_PEER_GID</code></dt> +<dd> +<p>(<code>uint64_t</code>) +This read-only option provides a connected peer’s primary group id, when known. +This is the effective group id of the peer when either the underlying +<code>listen()</code> or <code>connect()</code> calls were made, and is not forgeable. +This option is generally only available on POSIX systems, only on certain transports.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_PEER_PID" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_PEER_PID</code></dt> +<dd> +<p>(<code>uint64_t</code>) +This read-only option provides the process id of the connected peer, when known. +This option is only available on certain platforms and transports.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Applications should not assume that the process ID does not change, +as it may be possible for a process to pass a file descriptor between processes. +However, it is not possible for a nefarious application to forge the identity +of a well-behaved one using this method. +</td> +</tr> +</table> +</div> +</dd> +</dl> +</div> +<div id="NNG_OPT_PEER_UID" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_PEER_UID</code></dt> +<dd> +<p>(<code>uint64_t</code>) +This read-only option provides a connected peer’s user id. +This is the effective user id of the peer when either the underlying +<code>listen()</code> or <code>connect()</code> calls were made, and cannot be forged. +This option is generally only available on POSIX systems, on certain transports.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_PEER_ZONEID" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_PEER_ZONEID</code></dt> +<dd> +<p>(<code>uint64_t</code>) +This read-only option provides a connected peer’s the zone id. +Zones (and this option) are only supported on Solaris and illumos systems, on select transports.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_PEERNAME" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_PEERNAME</code></dt> +<dd> +<p>(string) +This read-only option is used to obtain the name of the peer protocol for the socket.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_PROTONAME" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_PROTONAME</code></dt> +<dd> +<p>(string) +This read-only option is used to obtain the name of the socket’s protocol.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer_get.3.html">nng_dialer_get(3)</a>, +<a href="nng_dialer_set.3.html">nng_dialer_set(3)</a>, +<a href="nng_listener_get.3.html">nng_listener_get(3)</a>, +<a href="nng_listener_set.3.html">nng_listener_set(3)</a>, +<a href="nng_pipe_get.3.html">nng_pipe_get(3)</a>, +<a href="nng_socket_get.3.html">nng_socket_get(3)</a>, +<a href="nng_socket_set.3.html">nng_socket_set(3)</a>, +<a href="nng_ipc_options.5.html">nng_ipc_options(5)</a>, +<a href="nng_tcp_options.5.html">nng_tcp_options(5)</a>, +<a href="nng_tls_options.5.html">nng_tls_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_opts_parse.3supp.html b/man/v1.7.2/nng_opts_parse.3supp.html new file mode 100644 index 00000000..c9059dae --- /dev/null +++ b/man/v1.7.2/nng_opts_parse.3supp.html @@ -0,0 +1,265 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_opts_parse(3supp) +--- +<h1>nng_opts_parse(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_opts_parse - parse command line options</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/options.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_optspec</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">o_name</span><span class="tok-p">;</span><span class="tok-w"> </span><span class="tok-c1">// Long style name (may be NULL for short only)</span> +<span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">o_short</span><span class="tok-p">;</span><span class="tok-w"> </span><span class="tok-c1">// Short option (no clustering!)</span> +<span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">o_val</span><span class="tok-p">;</span><span class="tok-w"> </span><span class="tok-c1">// Value stored on a good parse (>0)</span> +<span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">o_arg</span><span class="tok-p">;</span><span class="tok-w"> </span><span class="tok-c1">// Option takes an argument if true</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_optspec</span><span class="tok-p">;</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_opts_parse</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">argc</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">argv</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-n">nng_optspec</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">spec</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">arg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">idx</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_opts_parse()</code> is function is a supplemental function intended to +facilitate parsing command line arguments. +This function exists largely to stand in for <code>getopt()</code> from POSIX +systems, but it is available everywhere that <em>NNG</em> is, and it includes +some capabilities missing from <code>getopt()</code>.</p> +</div> +<div class="paragraph"> +<p>The function parses arguments from <code>main()</code> (using <em>argc</em> and <em>argv</em>), +starting at the index referenced by <em>idx</em>. +(New invocations typically set the value pointed to by <em>idx</em> to 1.)</p> +</div> +<div class="paragraph"> +<p>Options are parsed as specified by <em>spec</em> (see <a href="#_option_specification">Option Specification</a>.) +The value of the parsed option will be stored at the address indicated by +<em>val</em>, and the value of <em>idx</em> will be incremented to reflect the next +option to parse.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +For using this to parse command-line like strings that do not include +the command name itself, set the value referenced by <em>idx</em> to zero +instead of one. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>If the option had an argument, a pointer to that is returned at the address +referenced by <em>arg</em>.</p> +</div> +<div class="paragraph"> +<p>This function should be called repeatedly, until it returns either -1 +(indicating the end of options is reached) or a non-zero error code is +returned.</p> +</div> +<div class="sect2"> +<h3 id="_option_specification">Option Specification</h3> +<div class="paragraph"> +<p>The calling program must first create an array of <code>nng_optspec</code> structures +describing the options to be supported. +This structure has the following members:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>o_name</code></dt> +<dd> +<p>The long style name for the option, such as "verbose". +This will be parsed on the command line when it is prefixed with two dashes. +It may be <code>NULL</code> if only a short option is to be supported.</p> +</dd> +<dt class="hdlist1"><code>o_short</code></dt> +<dd> +<p>This is a single letter (at present only ASCII letters are supported). +These options appear as just a single letter, and are prefixed with a single dash on the command line. +The use of a slash in lieu of the dash is <em>not</em> supported, in order to avoid confusion with path name arguments. +This value may be set to 0 if no short option is needed.</p> +</dd> +<dt class="hdlist1"><code>o_val</code></dt> +<dd> +<p>This is a numeric value that is unique to this option. +This value is assigned by the application program, and must be non-zero +for a valid option. +If this is zero, then it indicates the end of the specifications, and the +rest of this structure is ignored. +The value will be returned to the caller in <em>val</em> by <code>nng_opts_parse()</code> when +this option is parsed from the command line.</p> +</dd> +<dt class="hdlist1"><code>o_arg</code></dt> +<dd> +<p>This value should be set to <code>true</code> if the option should take an argument.</p> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_long_options">Long Options</h3> +<div class="paragraph"> +<p>Long options are parsed from the <em>argv</em> array, and are indicated when +the element being scanned starts with two dashes. +For example, the "verbose" option would be specified as <code>--verbose</code> on +the command line. +If a long option takes an argument, it can either immediately follow +the option as the next element in <em>argv</em>, or it can be appended to +the option, separated from the option by an equals sign (<code>=</code>) or a +colon (<code>:</code>).</p> +</div> +</div> +<div class="sect2"> +<h3 id="_short_options">Short Options</h3> +<div class="paragraph"> +<p>Short options appear by themselves in an <em>argv</em> element, prefixed by a +dash (<code>-</code>). +If the short option takes an argument, it can either be appended in the +same element of <em>argv</em>, or may appear in the next <em>argv</em> element.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Option clustering, where multiple options can be crammed together in +a single <em>argv</em> element, is not supported by this function (yet). +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_prefix_matching">Prefix Matching</h3> +<div class="paragraph"> +<p>When using long options, the parser will match if it is equal to a prefix +of the <code>o_name</code> member of a option specification, provided that it do so +unambiguously (meaning it must not match any other option specification.)</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_example">EXAMPLE</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The following program fragment demonstrates this function.</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-w"> </span><span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-p">{</span><span class="tok-w"> </span><span class="tok-n">OPT_LOGFILE</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">OPT_VERBOSE</span><span class="tok-w"> </span><span class="tok-p">};</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">logfile</span><span class="tok-p">;</span><span class="tok-w"> </span><span class="tok-c1">// options to be set</span> +<span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">verbose</span><span class="tok-p">;</span> + +<span class="tok-w"> </span><span class="tok-k">static</span><span class="tok-w"> </span><span class="tok-n">nng_optspec</span><span class="tok-w"> </span><span class="tok-n">specs</span><span class="tok-p">[]</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-p">.</span><span class="tok-n">o_name</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s">"logfile"</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-p">.</span><span class="tok-n">o_short</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-sc">'D'</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-p">.</span><span class="tok-n">o_val</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">OPT_LOGFILE</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-p">.</span><span class="tok-n">o_arg</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-nb">true</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-p">},</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-p">.</span><span class="tok-n">o_name</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s">"verbose"</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-p">.</span><span class="tok-n">o_short</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-sc">'V'</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-p">.</span><span class="tok-n">o_val</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">OPT_VERBOSE</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-p">.</span><span class="tok-n">o_arg</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-nb">false</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-p">},</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-p">.</span><span class="tok-n">o_val</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">0</span><span class="tok-p">;</span><span class="tok-w"> </span><span class="tok-c1">// Terminate array</span> +<span class="tok-w"> </span><span class="tok-p">}</span> +<span class="tok-w"> </span><span class="tok-p">};</span> + +<span class="tok-w"> </span><span class="tok-k">for</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">idx</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">1</span><span class="tok-p">;;)</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">rv</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">opt</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">arg</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">rv</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">nng_opts_parse</span><span class="tok-p">(</span><span class="tok-n">argc</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">argv</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">specs</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-o">&</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-o">&</span><span class="tok-n">arg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-o">&</span><span class="tok-n">idx</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-n">rv</span><span class="tok-w"> </span><span class="tok-o">!=</span><span class="tok-w"> </span><span class="tok-mi">0</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-k">break</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-p">}</span> +<span class="tok-w"> </span><span class="tok-k">switch</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-n">opt</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-k">case</span><span class="tok-w"> </span><span class="tok-no">OPT_LOGFILE</span><span class="tok-p">:</span> +<span class="tok-w"> </span><span class="tok-n">logfile</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">arg</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-k">break</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-k">case</span><span class="tok-w"> </span><span class="tok-no">OPT_VERBOSE</span><span class="tok-p">:</span> +<span class="tok-w"> </span><span class="tok-n">verbose</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-nb">true</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-k">break</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-p">}</span> +<span class="tok-w"> </span><span class="tok-p">}</span> +<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-n">rv</span><span class="tok-w"> </span><span class="tok-o">!=</span><span class="tok-w"> </span><span class="tok-mi">-1</span><span class="tok-p">)</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">printf</span><span class="tok-p">(</span><span class="tok-s">"Options error: %s</span><span class="tok-se">\n</span><span class="tok-s">"</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_strerror</span><span class="tok-p">(</span><span class="tok-n">rv</span><span class="tok-p">));</span> +<span class="tok-w"> </span><span class="tok-n">exit</span><span class="tok-p">(</span><span class="tok-mi">1</span><span class="tok-p">);</span> +<span class="tok-w"> </span><span class="tok-p">}</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 if an option parsed correctly, -1 if +no more options are available to be parsed, or an error number otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EAMBIGUOUS</code> +</td> +<td class="hdlist2"> +<p>Parsed option matches more than one specification.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOARG</code> +</td> +<td class="hdlist2"> +<p>Option requires an argument, but one is not present.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid (unknown) argument is present.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pair.7.html b/man/v1.7.2/nng_pair.7.html new file mode 100644 index 00000000..c6d41b6c --- /dev/null +++ b/man/v1.7.2/nng_pair.7.html @@ -0,0 +1,217 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pair(7) +--- +<h1>nng_pair(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pair - pair protocol</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Version 0</div> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/pair0/pair.h></span></code></pre> +</div> +</div> +<div class="listingblock"> +<div class="title">Version 1</div> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/pair1/pair.h></span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>pair</em> protocol implements a peer-to-peer pattern, where +relationships between peers are one-to-one.</p> +</div> +<div class="sect2"> +<h3 id="_socket_operations">Socket Operations</h3> +<div class="paragraph"> +<p>The <a href="nng_pair_open.3.html"><code>nng_pair_open()</code></a> functions create a <em>pair</em> socket.</p> +</div> +<div class="paragraph"> +<p>Normally, this pattern will block when attempting to send a message if +no peer is able to receive the message.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Even though this mode may appear to be reliable, because back-pressure +prevents discarding messages most of the time, there are topologies involving +<em>devices</em> (see <a href="nng_device.3.html"><code>nng_device()</code></a>) or raw mode sockets +(see <a href="nng_options.5.html#NNG_OPT_RAW"><code>NNG_OPT_RAW</code></a>) where +messages may be discarded. +Applications that require reliable delivery semantics should consider using +<a href="nng_req.7.html"><em>req</em></a> sockets, or +implement their own acknowledgment layer on top of <em>pair</em> sockets. +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_versions">Protocol Versions</h3> +<div class="paragraph"> +<p>Version 0 is the legacy version of this protocol. +It lacks any header +information, and is suitable when building simple one-to-one topologies.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Use version 0 if you need to communicate with other implementations, +including the legacy <a href="https://github.com/nanomsg/nanomsg">nanomsg</a> library or +<a href="https://github.com/go-mangos/mangos">mangos</a>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Version 1 of the protocol offers improved protection against loops when +used with <a href="nng_device.3.html"><code>nng_device()</code></a>.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_polyamorous_mode">Polyamorous Mode</h3> +<div class="admonitionblock warning"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-warning" title="Warning"></i> +</td> +<td class="content"> +Polyamorous mode is deprecated, and support for it will likely +be removed in a future release. +Applications are strongly discouraged from making further use of it. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Normally pair sockets are for one-to-one communication, and a given peer +will reject new connections if it already has an active connection to another +peer.</p> +</div> +<div class="paragraph"> +<p><em>Polyamorous</em> mode changes this, to allow a socket to communicate with +multiple directly-connected peers. +This mode is enabled by opening a socket with the +<a href="nng_pair_open.3.html"><code>nng_pair1_open_poly()</code></a> +function</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Polyamorous mode is only available when using pair version 1. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>In polyamorous mode a socket can support many one-to-one connections. +In this mode, the application must +choose the remote peer to receive an outgoing message by setting the +<a href="nng_pipe.5.html"><code>nng_pipe</code></a> to use for the outgoing message with +the <a href="nng_msg_set_pipe.3.html"><code>nng_msg_set_pipe()</code></a> function.</p> +</div> +<div class="paragraph"> +<p>If no remote peer is specified by the sender, then the protocol will select +any available connected peer.</p> +</div> +<div class="paragraph"> +<p>Most often the value of the outgoing pipe will be obtained from an incoming +message using the <a href="nng_msg_get_pipe.3.html"><code>nng_msg_get_pipe()</code></a> function, +such as when replying to an incoming message.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Directed send <em>only</em> works with directly connected peers. +It will not function across <a href="nng_device.3.html">device</a> proxies. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>In order to prevent head-of-line blocking, if the peer on the given pipe +is not able to receive (or the pipe is no longer available, such as if the +peer has disconnected), then the message will be discarded with no notification +to the sender.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_options">Protocol Options</h3> +<div class="paragraph"> +<p>The following protocol-specific options are available.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><a href="nng_options.5.html#NNG_OPT_MAXTTL"><code>NNG_OPT_MAXTTL</code></a></dt> +<dd> +<p>(<code>int</code>, version 1 only). Maximum time-to-live.</p> +</dd> +<dt class="hdlist1"><code>NNG_OPT_PAIR1_POLY</code></dt> +<dd> +<p>(<code>bool</code>, version 1 only) This option is no longer supported. +Formerly it was used to configure <em>polyamorous</em> mode, but that mode +is now established by using the <code>nng_pair1_open_poly()</code> function.</p> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_headers">Protocol Headers</h3> +<div class="paragraph"> +<p>Version 0 of the pair protocol has no protocol-specific headers.</p> +</div> +<div class="paragraph"> +<p>Version 1 of the pair protocol uses a single 32-bit unsigned value. The +low-order (big-endian) byte of this value contains a "hop" count, and is +used in conjunction with the +<a href="nng_options.5.html#NNG_OPT_MAXTTL"><code>NNG_OPT_MAXTTL</code></a> option to guard against +device forwarding loops. +This value is initialized to 1, and incremented each time the message is +received by a new node.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_pair_open.3.html">nng_pair_open(3)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pair_open.3.html b/man/v1.7.2/nng_pair_open.3.html new file mode 100644 index 00000000..d5d8b8ad --- /dev/null +++ b/man/v1.7.2/nng_pair_open.3.html @@ -0,0 +1,117 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pair_open(3) +--- +<h1>nng_pair_open(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pair_open - create pair socket</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Version 0</div> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/pair0/pair.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pair0_open</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pair0_open_raw</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +<div class="listingblock"> +<div class="title">Version 1</div> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/pair1/pair.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pair1_open</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pair1_open_raw</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pair1_open_poly</span><span class="tok-p">(</span><span class="tok-n">nng_socktet</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_pair0_open()</code> and <code>nng_pair1_open()</code> functions +create a <a href="nng_pair.7.html"><em>pair</em></a> version 0 or version 1 +<a href="nng_socket.5.html">socket</a> and return it at the location pointed to by <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_pair0_open_raw()</code> and <code>nng_pair1_open_raw()</code> functions +create a <a href="nng_pair.7.html"><em>pair</em></a> version 0 or version 1 +<a href="nng_socket.5.html">socket</a> in +<a href="nng.7.html#raw_mode">raw</a> mode and return it at the location pointed to by <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_pair1_open_poly()</code> function opens a pair version 1 socket in +polyamorous mode.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Polyamorous mode is deprecated and should not be used in new applications. +The <code>nng_pair1_open_poly()</code> function will likely be removed in a future release. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng_pair.7.html">nng_pair(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pipe.5.html b/man/v1.7.2/nng_pipe.5.html new file mode 100644 index 00000000..768f6b6c --- /dev/null +++ b/man/v1.7.2/nng_pipe.5.html @@ -0,0 +1,113 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pipe(5) +--- +<h1>nng_pipe(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pipe - communications pipe</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_pipe_s</span><span class="tok-w"> </span><span class="tok-n">nng_pipe</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +An <code>nng_pipe</code> is a handle to a pipe object, which can be thought of as a single +connection. +(In most cases this is actually the case — the pipe is an abstraction for a +single TCP or IPC connection.) +Pipes are associated with either the listener or dialer that created them, +and therefore are also automatically associated with a single socket.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +The <code>nng_pipe</code> structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way gives the compiler a chance to perform +accurate type checks in functions passing values of this type. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Most applications should never concern themselves with individual pipes. +However it is possible to access a pipe when more information about the +source of a message is needed, or when more control is required over +message delivery. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Pipe objects are created by dialers (<a href="nng_dialer.5.html"><code>nng_dialer</code></a> objects) +and listeners (<a href="nng_listener.5.html"><code>nng_listener</code></a> objects).</p> +</div> +<div class="paragraph"> +<p>Pipe objects may be destroyed by the +<a href="nng_pipe_close.3.html"><code>nng_pipe_close()</code></a> function. +They are also closed when the dialer or listener that created them is closed, +or when the remote peer closes the underlying connection.</p> +</div> +<div class="sect2"> +<h3 id="NNG_PIPE_INITIALIZER">Initialization</h3> +<div class="paragraph"> +<p>A pipe may be initialized using the macro <code>NNG_PIPE_INITIALIZER</code> +before it is opened, to prevent confusion with valid open pipes.</p> +</div> +<div class="paragraph"> +<p>For example:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">NNG_PIPE_INITIALIZER</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_get_pipe.3.html">nng_msg_get_pipe(3)</a>, +<a href="nng_pipe_close.3.html">nng_pipe_close(3)</a>, +<a href="nng_pipe_getopt.3.html">nng_pipe_getopt(3)</a>, +<a href="nng_pipe_dialer.3.html">nng_pipe_dialer(3)</a>, +<a href="nng_pipe_id.3.html">nng_pipe_id(3)</a>, +<a href="nng_pipe_listener.3.html">nng_pipe_listener(3)</a>, +<a href="nng_pipe_socket.3.html">nng_pipe_socket(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pipe_close.3.html b/man/v1.7.2/nng_pipe_close.3.html new file mode 100644 index 00000000..93624afc --- /dev/null +++ b/man/v1.7.2/nng_pipe_close.3.html @@ -0,0 +1,89 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pipe_close(3) +--- +<h1>nng_pipe_close(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pipe_close - close pipe</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_close</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_pipe_close()</code> function closes the supplied pipe, <em>p</em>. +Messages that have been submitted for sending may be flushed or delivered, +depending upon the transport.</p> +</div> +<div class="paragraph"> +<p>Further attempts to use the pipe after this call returns will result +in <code>NNG_ECLOSED</code>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Pipes are automatically closed when their creator closes, or when the +remote peer closes the underlying connection. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The pipe <em>p</em> is already closed or was never opened.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_pipe.5.html">nng_pipe(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pipe_dialer.3.html b/man/v1.7.2/nng_pipe_dialer.3.html new file mode 100644 index 00000000..7183efaa --- /dev/null +++ b/man/v1.7.2/nng_pipe_dialer.3.html @@ -0,0 +1,65 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pipe_dialer(3) +--- +<h1>nng_pipe_dialer(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pipe_dialer - return dialer that created pipe</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_dialer</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_pipe_dialer()</code> function returns the <a href="nng_dialer.5.html"><code>nng_dialer</code></a> +that created the pipe <em>p</em>. +If the pipe was not created by a dialer, then the returned value will +have an identifier (<a href="nng_dialer_id.3.html"><code>nng_dialer_id()</code></a>) of <code>-1</code>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the dialer that created the pipe, unless it was +not created by a dialer, in which case a value initialized with +<code>NNG_DIALER_INITIALIZER</code> will be returned.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_pipe.5.html">nng_pipe(5)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pipe_get.3.html b/man/v1.7.2/nng_pipe_get.3.html new file mode 100644 index 00000000..b6929ffd --- /dev/null +++ b/man/v1.7.2/nng_pipe_get.3.html @@ -0,0 +1,254 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pipe_get(3) +--- +<h1>nng_pipe_get(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pipe_get - get pipe option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valszp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_bool</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">bvalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_int</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ivalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_ms</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">durp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_addr</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sap</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_string</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">strp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_size</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">zp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_get_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u64p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <code>nng_pipe_get()</code> functions are used to retrieve option values for +the <a href="nng_pipe.5.html">pipe</a> <em>p</em>. +The actual options that may be retrieved in this way +vary, and many are documented in <a href="nng_options.5.html">nng_options(5)</a>. +Additionally some transport-specific options and protocol-specific options are +documented with the transports and protocols themselves.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +All options on a pipe are read-only values. +Modification of options may be done before the pipe is created using +<a href="nng_listener_set.3.html"><code>nng_listener_set()</code></a> or +<a href="nng_dialer_get.3.html"><code>nng_dialer_set()</code></a>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Any option that is set on a dialer or listener will normally be retrievable +from pipes created by that dialer or listener.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the pipe <em>p</em>.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_pipe_get()</code></dt> +<dd> +<p>This is untyped, and can be used to retrieve the value of any option. +A pointer to a buffer to receive the value in <em>val</em>, and the size of the +buffer shall be stored at the location referenced by <em>valszp</em>.<br> +<br> +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>valszp</em>. +If the caller’s buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +size returned in <em>valszp</em> does not exceed the original buffer size.<br> +<br> +It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>valszp</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_pipe_get_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The value will be stored at <em>bvalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_get_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The value will be stored at <em>ivalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_get_ms()</code></dt> +<dd> +<p>This function is used to retrieve time durations +(<a href="nng_duration.5.html"><code>nng_duration</code></a>) in milliseconds, which are stored in +<em>durp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_get_ptr()</code></dt> +<dd> +<p>This function is used to retrieve a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_get_size()</code></dt> +<dd> +<p>This function is used to retrieve a size into the pointer <em>zp</em>, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_get_addr()</code></dt> +<dd> +<p>This function is used to retrieve an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +into <em>sap</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_get_string()</code></dt> +<dd> +<p>This function is used to retrieve a string into <em>strp</em>. +This string is created from the source using <a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_get_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value into the value +referenced by <em>u64p</em>. +This is typically used for options +related to identifiers, network numbers, and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>p</em> does not refer to an open pipe.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Size of destination <em>val</em> too small for object.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is write-only.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer_set.3.html">nng_dialer_set(3)</a> +<a href="nng_socket_get.3.html">nng_socket_get(3)</a>, +<a href="nng_listener_set.3.html">nng_listener_set(3)</a> +<a href="nng_msg_get_pipe.3.html">nng_msg_get_pipe(3)</a> +<a href="nng_strdup.3.html">nng_strdup(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_strfree.3.html">nng_strfree(3)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_pipe.5.html">nng_pipe(5)</a>, +<a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pipe_getopt.3.html b/man/v1.7.2/nng_pipe_getopt.3.html new file mode 100644 index 00000000..0618fc22 --- /dev/null +++ b/man/v1.7.2/nng_pipe_getopt.3.html @@ -0,0 +1,266 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pipe_getopt(3) +--- +<h1>nng_pipe_getopt(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pipe_getopt - get pipe option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_getopt</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valszp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_getopt_bool</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">bvalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_getopt_int</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ivalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_getopt_ms</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">durp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_getopt_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_getopt_sockaddr</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sap</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_getopt_string</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">strp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_getopt_size</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">zp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_getopt_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u64p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +These functions are deprecated. Please see <a href="nng_pipe_get.3.html">nng_pipe_get</a>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p> +The <code>nng_pipe_getopt()</code> functions are used to retrieve option values for +the <a href="nng_pipe.5.html">pipe</a> <em>p</em>. +The actual options that may be retrieved in this way +vary, and many are documented in <a href="nng_options.5.html">nng_options(5)</a>. +Additionally some transport-specific options and protocol-specific options are +documented with the transports and protocols themselves.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +All options on a pipe are read-only values. +Modification of options may be done before the pipe is created using +<a href="nng_listener_setopt.3.html"><code>nng_listener_setopt()</code></a> or +<a href="nng_dialer_getopt.3.html"><code>nng_dialer_setopt()</code></a>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Any option that is set on a dialer or listener will normally be retrievable +from pipes created by that dialer or listener.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the pipe <em>p</em>.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_pipe_getopt()</code></dt> +<dd> +<p>This is untyped, and can be used to retrieve the value of any option. +A pointer to a buffer to receive the value in <em>val</em>, and the size of the +buffer shall be stored at the location referenced by <em>valszp</em>.<br> +<br> +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>valszp</em>. +If the caller’s buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +size returned in <em>valszp</em> does not exceed the original buffer size.<br> +<br> +It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>valszp</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_pipe_getopt_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The value will be stored at <em>bvalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_getopt_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The value will be stored at <em>ivalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_getopt_ms()</code></dt> +<dd> +<p>This function is used to retrieve time durations +(<a href="nng_duration.5.html"><code>nng_duration</code></a>) in milliseconds, which are stored in +<em>durp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_getopt_ptr()</code></dt> +<dd> +<p>This function is used to retrieve a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_getopt_size()</code></dt> +<dd> +<p>This function is used to retrieve a size into the pointer <em>zp</em>, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_getopt_sockaddr()</code></dt> +<dd> +<p>This function is used to retrieve an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +into <em>sap</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_getopt_string()</code></dt> +<dd> +<p>This function is used to retrieve a string into <em>strp</em>. +This string is created from the source using <a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_pipe_getopt_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value into the value +referenced by <em>u64p</em>. +This is typically used for options +related to identifiers, network numbers, and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>p</em> does not refer to an open pipe.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Size of destination <em>val</em> too small for object.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is write-only.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer_setopt.3.html">nng_dialer_setopt(3)</a> +<a href="nng_getopt.3.html">nng_getopt(3)</a>, +<a href="nng_listener_setopt.3.html">nng_listener_setopt(3)</a> +<a href="nng_msg_get_pipe.3.html">nng_msg_get_pipe(3)</a> +<a href="nng_strdup.3.html">nng_strdup(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_strfree.3.html">nng_strfree(3)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_pipe.5.html">nng_pipe(5)</a>, +<a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pipe_id.3.html b/man/v1.7.2/nng_pipe_id.3.html new file mode 100644 index 00000000..6f6a9241 --- /dev/null +++ b/man/v1.7.2/nng_pipe_id.3.html @@ -0,0 +1,78 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pipe_id(3) +--- +<h1>nng_pipe_id(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pipe_id - return numeric pipe identifier</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_id</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_pipe_id()</code> function returns a positive identifier for the pipe <em>p</em>, +if it is valid. +Otherwise it returns <code>-1</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +A pipe is considered valid if it was ever created by the socket. +Pipes that are allocated on the stack or statically should be +initialized with the macro +<a href="nng_pipe.5.html#NNG_PIPE_INITIALIZER"><code>NNG_PIPE_INITIALIZER</code></a> to ensure that +they cannot be confused with a valid pipe. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the positive value for the pipe identifier, or +<code>-1</code> if the pipe is invalid.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_pipe.5.html">nng_pipe(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pipe_listener.3.html b/man/v1.7.2/nng_pipe_listener.3.html new file mode 100644 index 00000000..96a57588 --- /dev/null +++ b/man/v1.7.2/nng_pipe_listener.3.html @@ -0,0 +1,65 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pipe_listener(3) +--- +<h1>nng_pipe_listener(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pipe_listener - return listener that created pipe</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_listener</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_pipe_listener()</code> function returns the <a href="nng_listener.5.html"><code>nng_listener</code></a> +that created the pipe <em>p</em>. +If the pipe was not created by a listener, then the returned value will +have an identifier (<a href="nng_listener_id.3.html"><code>nng_listener_id()</code></a>) of <code>-1</code>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the listener that created the pipe, unless it was +not created by a listener, in which case a value initialized with +<code>NNG_LISTENER_INITIALIZER</code> will be returned.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_pipe.5.html">nng_pipe(5)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pipe_notify.3.html b/man/v1.7.2/nng_pipe_notify.3.html new file mode 100644 index 00000000..864f8dfb --- /dev/null +++ b/man/v1.7.2/nng_pipe_notify.3.html @@ -0,0 +1,170 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pipe_notify(3) +--- +<h1>nng_pipe_notify(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pipe_notify - register pipe notification callback</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_PIPE_EV_ADD_PRE</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_PIPE_EV_ADD_POST</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_PIPE_EV_REM_POST</span><span class="tok-p">,</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_pipe_ev</span><span class="tok-p">;</span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-o">*</span><span class="tok-n">nng_pipe_cb</span><span class="tok-p">)(</span><span class="tok-n">nng_pipe</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_pipe_ev</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_notify</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_pipe_ev</span><span class="tok-w"> </span><span class="tok-n">ev</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_pipe_cb</span><span class="tok-w"> </span><span class="tok-n">cb</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">arg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_pipe_notify()</code> function registers the callback function <em>cb</em> +to be called whenever a <a href="nng_pipe.5.html">pipe</a> the pipe event specified by +<em>ev</em> occurs on the socket <em>s</em>. +The callback <em>cb</em> will be passed <em>arg</em> as its final argument.</p> +</div> +<div class="paragraph"> +<p>A different callback may be supplied for each event. +Each event may have at most one callback registered. +Registering a callback implicitly unregisters any previously registered.</p> +</div> +<div class="paragraph"> +<p>The following pipe events are supported:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_PIPE_EV_ADD_PRE</code></dt> +<dd> +<p>This event occurs after a connection and negotiation +has completed, but before the pipe is added to the socket. +If the pipe is closed (using <a href="nng_pipe_close.3.html"><code>nng_pipe_close()</code></a>) at +this point, the socket will never see the pipe, and no further events will +occur for the given pipe.</p> +</dd> +<dt class="hdlist1"><code>NNG_PIPE_EV_ADD_POST</code></dt> +<dd> +<p>This event occurs after the pipe is fully added to +the socket. +Prior to this time, it is not possible to communicate over the pipe with +the socket.</p> +</dd> +<dt class="hdlist1"><code>NNG_PIPE_EV_REM_POST</code></dt> +<dd> +<p>This event occurs after the pipe has been removed +from the socket. +The underlying transport may be closed at this point, and it is not +possible communicate using this pipe.</p> +</dd> +</dl> +</div> +<div class="admonitionblock warning"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-warning" title="Warning"></i> +</td> +<td class="content"> +The callback <em>cb</em> function must <strong>not</strong> attempt to perform any +accesses to the socket, as it is called with a lock on the socket held! +Doing so would thus result in a deadlock. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The callback <em>cb</em> may close a pipe for any reason by simply closing +it using <a href="nng_pipe_close.3.html"><code>nng_pipe_close()</code></a>. +This might be done before the pipe is added to the socket (during +<code>NNG_PIPE_EV_ADD_PRE</code>), for example, if the remote peer is not authorized. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It is possible to register the same <em>cb</em> and <em>arg</em> for different events +by calling this function separately for different values of <em>ev</em>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function ignores invalid values for <em>ev</em>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> does not refer to an open socket.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_pipe_close.3.html">nng_pipe_close(3)</a>, +<a href="nng_pipe_getopt.3.html">nng_pipe_getopt(3)</a>, +<a href="nng_pipe.5.html">nng_pipe(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pipe_socket.3.html b/man/v1.7.2/nng_pipe_socket.3.html new file mode 100644 index 00000000..5ba3159a --- /dev/null +++ b/man/v1.7.2/nng_pipe_socket.3.html @@ -0,0 +1,74 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pipe_socket(3) +--- +<h1>nng_pipe_socket(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pipe_socket - return owning socket for pipe</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-nf">nng_pipe_socket</span><span class="tok-p">(</span><span class="tok-n">nng_pipe</span><span class="tok-w"> </span><span class="tok-n">p</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_pipe_socket()</code> function returns the <a href="nng_socket.5.html"><code>nng_socket</code></a> +associated with the pipe <em>p</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The returned socket may be closed or in the process of closing, in +which case it will not be usable with other functions. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the socket associated with the pipe.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_pipe.5.html">nng_pipe(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pub.7.html b/man/v1.7.2/nng_pub.7.html new file mode 100644 index 00000000..69d2f1ec --- /dev/null +++ b/man/v1.7.2/nng_pub.7.html @@ -0,0 +1,99 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pub(7) +--- +<h1>nng_pub(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pub - publisher protocol</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/pubsub0/pub.h></span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>pub</em> protocol is one half of a publisher/subscriber pattern. +In this pattern, a publisher sends data, which is broadcast to all +subscribers. +The subscribing applications only see the data to which +they have subscribed.</p> +</div> +<div class="paragraph"> +<p>The <em>pub</em> protocol is the publisher side, and the +<a href="nng_sub.7.html"><em>sub</em></a> protocol is the subscriber side.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +In this implementation, the publisher delivers all messages to all +subscribers. +The subscribers maintain their own subscriptions, and filter them locally. +Thus, this pattern should not be used in an attempt to reduce bandwidth +consumption. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The topics that subscribers subscribe to is just the first part of +the message body. +Applications should construct their messages accordingly.</p> +</div> +<div class="sect2"> +<h3 id="_socket_operations">Socket Operations</h3> +<div class="paragraph"> +<p>The <a href="nng_pub_open.3.html"><code>nng_pub0_open()</code></a> functions create a publisher socket. +This socket may be used to send messages, but is unable to receive them. +Attempts to receive messages will result in <code>NNG_ENOTSUP</code>.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_versions">Protocol Versions</h3> +<div class="paragraph"> +<p>Only version 0 of this protocol is supported. +(At the time of writing, no other versions of this protocol have been defined.)</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_options">Protocol Options</h3> +<div class="paragraph"> +<p>The <em>pub</em> protocol has no protocol-specific options.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_headers">Protocol Headers</h3> +<div class="paragraph"> +<p>The <em>pub</em> protocol has no protocol-specific headers.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_pub_open.3.html">nng_pub_open(3)</a>, +<a href="nng_sub.7.html">nng_sub(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pub_open.3.html b/man/v1.7.2/nng_pub_open.3.html new file mode 100644 index 00000000..fe1d9260 --- /dev/null +++ b/man/v1.7.2/nng_pub_open.3.html @@ -0,0 +1,87 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pub_open(3) +--- +<h1>nng_pub_open(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pub_open - create pub socket</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/pubsub0/pub.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pub0_open</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pub0_open_raw</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_pub0_open()</code> function creates a <a href="nng_pub.7.html"><em>pub</em></a> version 0 +<a href="nng_socket.5.html">socket</a> and returns it at the location pointed to by <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_pub0_open_raw()</code> function creates a <a href="nng_pub.7.html"><em>pub</em></a> version 0 +<a href="nng_socket.5.html">socket</a> in +<a href="nng.7.html#raw_mode">raw</a> mode and returns it at the location pointed to by <em>s</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng_pub.7.html">nng_pub(7)</a>, +<a href="nng_sub.7.html">nng_sub(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pull.7.html b/man/v1.7.2/nng_pull.7.html new file mode 100644 index 00000000..7c114432 --- /dev/null +++ b/man/v1.7.2/nng_pull.7.html @@ -0,0 +1,85 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pull(7) +--- +<h1>nng_pull(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pull - pull protocol</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/pipeline0/pull.h></span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>pull</em> protocol is one half of a pipeline pattern. +The other half is the <a href="nng_push.7.html"><em>push</em></a> protocol.</p> +</div> +<div class="paragraph"> +<p>In the pipeline pattern, pushers distribute messages to pullers. +Each message sent +by a pusher will be sent to one of its peer pullers, +chosen in a round-robin fashion +from the set of connected peers available for receiving. +This property makes this pattern useful in load-balancing scenarios.</p> +</div> +<div class="sect2"> +<h3 id="_socket_operations">Socket Operations</h3> +<div class="paragraph"> +<p>The <a href="nng_pull_open.3.html"><code>nng_pull0_open()</code></a> functions create a puller socket. +This socket may be used to receive messages, but is unable to send them. +Attempts to send messages will result in <code>NNG_ENOTSUP</code>.</p> +</div> +<div class="paragraph"> +<p>When receiving messages, the <em>pull</em> protocol accepts messages as +they arrive from peers. +If two peers both have a message ready, the +order in which messages are handled is undefined.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_versions">Protocol Versions</h3> +<div class="paragraph"> +<p>Only version 0 of this protocol is supported. +(At the time of writing, no other versions of this protocol have been defined.)</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_options">Protocol Options</h3> +<div class="paragraph"> +<p>The <em>pull</em> protocol has no protocol-specific options.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_headers">Protocol Headers</h3> +<div class="paragraph"> +<p>The <em>pull</em> protocol has no protocol-specific headers.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_pull_open.3.html">nng_pull_open(3)</a>, +<a href="nng_push.7.html">nng_push(7)</a>, +<a href="nng.7.html">nng(7)</a>,</p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_pull_open.3.html b/man/v1.7.2/nng_pull_open.3.html new file mode 100644 index 00000000..f130f8be --- /dev/null +++ b/man/v1.7.2/nng_pull_open.3.html @@ -0,0 +1,87 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_pull_open(3) +--- +<h1>nng_pull_open(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_pull_open - create pull socket</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/pipeline0/pull.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pull0_open</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_pull0_open_raw</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_pull0_open()</code> function creates a <a href="nng_pull.7.html"><em>pull</em></a> version 0 +<a href="nng_socket.5.html">socket</a> and returns it at the location pointed to by <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_pull0_open_raw()</code> function creates a <a href="nng_pull.7.html"><em>pull</em></a> version 0 +<a href="nng_socket.5.html">socket</a> in +<a href="nng.7.html#raw_mode">raw</a> mode and returns it at the location pointed to by <em>s</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng_pull.7.html">nng_pull(7)</a>, +<a href="nng_push.7.html">nng_push(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_push.7.html b/man/v1.7.2/nng_push.7.html new file mode 100644 index 00000000..3bd0eff0 --- /dev/null +++ b/man/v1.7.2/nng_push.7.html @@ -0,0 +1,123 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_push(7) +--- +<h1>nng_push(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_push - push protocol</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/pipeline0/push.h></span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>push</em> protocol is one half of a pipeline pattern. +The other side is the <a href="nng_pull.7.html"><em>pull</em></a> protocol.</p> +</div> +<div class="paragraph"> +<p>In the pipeline pattern, pushers distribute messages to pullers. +Each message sent by a pusher will be sent to one of its peer pullers, +chosen in a round-robin fashion +from the set of connected peers available for receiving. +This property makes this pattern useful in load-balancing scenarios.</p> +</div> +<div class="sect2"> +<h3 id="_socket_operations">Socket Operations</h3> +<div class="paragraph"> +<p>The <a href="nng_push_open.3.html"><code>nng_push0_open()</code></a> call creates a pusher socket. +This socket may be used to send messages, but is unable to receive them. +Attempts to receive messages will result in <code>NNG_ENOTSUP</code>.</p> +</div> +<div class="paragraph"> +<p>Send operations will observe flow control (back-pressure), so that +only peers capable of accepting a message will be considered. +If no peer is available to receive a message, then the send operation will +wait until one is available, or the operation times out.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Although the pipeline protocol honors flow control, and attempts +to avoid dropping messages, no guarantee of delivery is made. +Furthermore, as there is no capability for message acknowledgment, +applications that need reliable delivery are encouraged to consider the +<a href="nng_req.7.html"><em>req</em></a> protocol instead. +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_versions">Protocol Versions</h3> +<div class="paragraph"> +<p>Only version 0 of this protocol is supported. +(At the time of writing, no other versions of this protocol have been defined.)</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_options">Protocol Options</h3> +<div class="dlist"> +<dl> +<dt class="hdlist1"><a href="nng_options.5.html#NNG_OPT_SENDBUF"><code>NNG_OPT_SENDBUF</code></a></dt> +<dd> +<p>(<code>int</code>, 0 - 8192) +Normally this is set to zero, indicating that send operations are unbuffered. +In unbuffered operation, send operations will wait until a suitable peer is available to receive the message. +If this is set to a positive value (up to 8192), then an intermediate buffer is +provided for the socket with the specified depth (in messages).</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Transport layer buffering may occur in addition to any socket + buffer determined by this option. +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_headers">Protocol Headers</h3> +<div class="paragraph"> +<p>The <em>push</em> protocol has no protocol-specific headers.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_push_open.3.html">nng_push(3)</a>, +<a href="nng_pull.7.html">nng_pull(7)</a>, +<a href="nng_req.7.html">nng_req(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_push_open.3.html b/man/v1.7.2/nng_push_open.3.html new file mode 100644 index 00000000..e1c75eef --- /dev/null +++ b/man/v1.7.2/nng_push_open.3.html @@ -0,0 +1,87 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_push_open(3) +--- +<h1>nng_push_open(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_push_open - create push socket</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/pipeline0/push.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_push0_open</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_push0_open_raw</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_push0_open()</code> function creates a <a href="nng_push.7.html"><em>push</em></a> version 0 +<a href="nng_socket.5.html">socket</a> and returns it at the location pointed to by <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_push0_open_raw()</code> function creates a <a href="nng_push.7.html"><em>push</em></a> version 0 +<a href="nng_socket.5.html">socket</a> in +<a href="nng.7.html#raw_mode">raw</a> mode and returns it at the location pointed to by <em>s</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng_pull.7.html">nng_pull(7)</a>, +<a href="nng_push.7.html">nng_push(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_random.3supp.html b/man/v1.7.2/nng_random.3supp.html new file mode 100644 index 00000000..78c1b9fd --- /dev/null +++ b/man/v1.7.2/nng_random.3supp.html @@ -0,0 +1,63 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_random(3supp) +--- +<h1>nng_random(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_random - get random number</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">uint32_t</span><span class="tok-w"> </span><span class="tok-nf">nng_random</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_random()</code> returns a random number. +The value returned is suitable for use with cryptographic functions such as +key generation. +The value is obtained using platform specific cryptographically strong random +number facilities when available.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Random number.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_recv.3.html b/man/v1.7.2/nng_recv.3.html new file mode 100644 index 00000000..47ee389c --- /dev/null +++ b/man/v1.7.2/nng_recv.3.html @@ -0,0 +1,194 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_recv(3) +--- +<h1>nng_recv(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_recv - recv data</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_recv</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">data</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sizep</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_recv()</code> receives a message.</p> +</div> +<div class="paragraph"> +<p>The <em>flags</em> is a bit mask that may contain any of the following values:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_FLAG_NONBLOCK</code></dt> +<dd> +<p>The function returns immediately, even if no message is available. +Without this flag, the function will wait until a message is received +by the socket <em>s</em>, or any configured timer expires.</p> +</dd> +<dt class="hdlist1"><code>NNG_FLAG_ALLOC</code></dt> +<dd> +<p>If this flag is present, then a zero-copy mode is used. +In this case the caller must set the value of <em>data</em> to the location +of another pointer (of type <code>void *</code>), and the <em>sizep</em> pointer must be set +to a location to receive the size of the message body. +The function will then allocate a message buffer +(as if by <a href="nng_alloc.3.html"><code>nng_alloc()</code></a>), fill it with +the message body, and store it at the address referenced by <em>data</em>, and update +the size referenced by <em>sizep</em>. +The caller is responsible for disposing of the received buffer either by +the <a href="nng_free.3.html"><code>nng_free()</code></a> function or passing the message (also +with the <code>NNG_FLAG_ALLOC</code> flag) in a call to <a href="nng_send.3.html"><code>nng_send()</code></a>.</p> +</dd> +</dl> +</div> +<div class="paragraph"> +<p>If the special flag <code>NNG_FLAG_ALLOC</code> (see above) is not specified, then the +caller must set <em>data</em> to a buffer to receive the message body content, +and must store the size of that buffer at the location pointed to by <em>sizep</em>. +When the function returns, if it is successful, the size at <em>sizep</em> will be +updated with the actual message body length copied into <em>data</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The semantics of what receiving a message means vary from protocol to +protocol, so examination of the protocol documentation is encouraged. +(For example, with a <a href="nng_req.7.html"><em>req</em></a> socket a message may only be received +after a request has been sent, and a <a href="nng_sub.7.html"><em>sub</em></a> socket +may only receive messages corresponding to topics to which it has subscribed.) +Furthermore, some protocols may not support receiving data at all, such as +<a href="nng_pub.7.html"><em>pub</em></a>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The <code>NNG_FLAG_ALLOC</code> flag can be used to reduce data copies, thereby +increasing performance, particularly if the buffer is reused to send +a response using the same flag. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EAGAIN</code> +</td> +<td class="hdlist2"> +<p>The operation would block, but <code>NNG_FLAG_NONBLOCK</code> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid set of <em>flags</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EMSGSIZE</code> +</td> +<td class="hdlist2"> +<p>The received message did not fit in the size provided.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol for socket <em>s</em> does not support receiving.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> cannot receive data in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>The operation timed out.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_alloc.3.html">nng_alloc(3)</a>, +<a href="nng_free.3.html">nng_free(3)</a>, +<a href="nng_recvmsg.3.html">nng_recvmsg(3)</a>, +<a href="nng_send.3.html">nng_send(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_recv_aio.3.html b/man/v1.7.2/nng_recv_aio.3.html new file mode 100644 index 00000000..043bb352 --- /dev/null +++ b/man/v1.7.2/nng_recv_aio.3.html @@ -0,0 +1,164 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_recv_aio(3) +--- +<h1>nng_recv_aio(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_recv_aio - receive message asynchronously</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_recv_aio</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_recv_aio()</code> receives a <a href="nng_msg.5.html">message</a> using the +<a href="nng_socket.5.html">socket</a> <em>s</em> asynchronously.</p> +</div> +<div class="paragraph"> +<p>When a message is successfully received by the socket, it is +stored in the <em>aio</em> by an internal call equivalent to +<a href="nng_aio_set_msg.3.html"><code>nng_aio_set_msg()</code></a>, then the completion +callback on the <em>aio</em> is executed. +In this case, <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a> will +return zero. +The callback function is responsible for retrieving the message +and disposing of it appropriately.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Failing to accept and dispose of messages in this +case can lead to memory leaks. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>If for some reason the asynchronous receive cannot be completed +successfully (including by being canceled or timing out), then +the callback will still be executed, +but <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a> will be non-zero.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The semantics of what receiving a message means varies from protocol to +protocol, so examination of the protocol documentation is encouraged. +(For example, with a <a href="nng_pub.7.html"><em>pub</em></a> socket the data is broadcast, so that +any peers who have a suitable subscription will be able to receive it using +<a href="nng_recv.3.html"><code>nng_recv()</code></a> or a similar function.) +Furthermore, some protocols may not support receiving (such as +<a href="nng_pub.7.html"><em>pub</em></a>) or may require other conditions. +(For example, <a href="nng_req.7.html"><em>req</em></a> sockets cannot normally receive data, which +are replies to requests, until they have first sent a request.) +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None. (The operation completes asynchronously.)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was aborted.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol for socket <em>s</em> does not support receiving.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> cannot receive data in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>The receive timeout expired.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_get_msg.3.html">nng_aio_get_msg(3)</a>, +<a href="nng_aio_set_msg.3.html">nng_aio_set_msg(3)</a>, +<a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_recvmsg.3.html b/man/v1.7.2/nng_recvmsg.3.html new file mode 100644 index 00000000..b375aeca --- /dev/null +++ b/man/v1.7.2/nng_recvmsg.3.html @@ -0,0 +1,165 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_recvmsg(3) +--- +<h1>nng_recvmsg(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_recvmsg - receive a message</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_recvmsg</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">msgp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_recvmsg()</code> receives a message on socket <em>s</em>, storing the +received message at the location pointed to by <em>msgp</em>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Using this function gives access to the message structure, and thus may +offer more functionality than the simpler <a href="nng_recv.3.html"><code>nng_recv()</code></a> function. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>flags</em> may contain the following value:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_FLAG_NONBLOCK</code></dt> +<dd> +<p>The function returns immediately, even if no message is available. +Without this flag, the function will wait until a message is received +by the socket <em>s</em>, or any configured timer expires.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The semantics of what receiving a message means vary from protocol to +protocol, so examination of the protocol documentation is encouraged. +(For example, with an <a href="nng_req.7.html"><em>req</em></a> socket a message may only be received +after a request has been sent, and an <a href="nng_sub.7.html"><em>sub</em></a> socket +may only receive messages corresponding to topics to which it has subscribed.) +Furthermore, some protocols may not support receiving data at all, such as +<a href="nng_pub.7.html"><em>pub</em></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EAGAIN</code> +</td> +<td class="hdlist2"> +<p>The operation would block, but <code>NNG_FLAG_NONBLOCK</code> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid set of <em>flags</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol for socket <em>s</em> does not support receiving.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> cannot receive data in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>The operation timed out.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_free.3.html">nng_msg_free(3)</a>, +<a href="nng_recv.3.html">nng_recv(3)</a>, +<a href="nng_sendmsg.3.html">nng_sendmsg(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_rep.7.html b/man/v1.7.2/nng_rep.7.html new file mode 100644 index 00000000..d820b063 --- /dev/null +++ b/man/v1.7.2/nng_rep.7.html @@ -0,0 +1,122 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_rep(7) +--- +<h1>nng_rep(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_rep - reply protocol</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/reqrep0/rep.h></span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>rep</em> protocol is one half of a request/reply pattern. +In this pattern, a requester sends a message to one replier, who +is expected to reply. +The request is resent if no reply arrives, +until a reply is received or the request times out.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This protocol is useful in setting up RPC-like services. +It is also reliable, in that a requester will keep retrying until +a reply is received. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>rep</em> protocol is the replier side, and the +<a href="nng_req.7.html"><em>req</em></a> protocol is the requester side.</p> +</div> +<div class="sect2"> +<h3 id="_socket_operations">Socket Operations</h3> +<div class="paragraph"> +<p>The <a href="nng_rep_open.3.html"><code>nng_rep0_open()</code></a> functions create a replier socket. +This socket may be used to receive messages (requests), and then to send +replies.</p> +</div> +<div class="paragraph"> +<p>Generally a reply can only be sent after receiving a request.</p> +</div> +<div class="paragraph"> +<p>Send operations will result in <code>NNG_ESTATE</code> if no corresponding request +was previously received.</p> +</div> +<div class="paragraph"> +<p>Likewise, only one receive operation may be pending at a time. +Any additional concurrent receive operations will result in <code>NNG_ESTATE</code>.</p> +</div> +<div class="paragraph"> +<p><a href="nng.7.html#raw_mode">Raw</a> mode sockets ignore all these restrictions.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_context_operations">Context Operations</h3> +<div class="paragraph"> +<p>This protocol supports the creation of <a href="nng_ctx.5.html">contexts</a> for concurrent +use cases using <a href="nng_ctx_open.3.html"><code>nng_ctx_open()</code></a>.</p> +</div> +<div class="paragraph"> +<p>Each context may have at most one outstanding request, and operates +independently of the others. +The restrictions for order of operations with sockets apply equally +well for contexts, except that each context will be treated as if it were +a separate socket.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_versions">Protocol Versions</h3> +<div class="paragraph"> +<p>Only version 0 of this protocol is supported. +(At the time of writing, no other versions of this protocol have been defined.)</p> +</div> +<div class="sect3"> +<h4 id="_protocol_options">Protocol Options</h4> +<div class="paragraph"> +<p>The <em>rep</em> protocol has no protocol-specific options.</p> +</div> +</div> +<div class="sect3"> +<h4 id="_protocol_headers">Protocol Headers</h4> +<div class="paragraph"> +<p> +The <em>rep</em> protocol uses a <em>backtrace</em> in the header. +This is more fully documented in the <a href="nng_req.7.html"><em>req</em></a> manual.</p> +</div> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_rep_open.3.html">nng_rep_open(3)</a>, +<a href="nng.7.html">nng(7)</a>, +<a href="nng_req.7.html">nng_req(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_rep_open.3.html b/man/v1.7.2/nng_rep_open.3.html new file mode 100644 index 00000000..498b45f2 --- /dev/null +++ b/man/v1.7.2/nng_rep_open.3.html @@ -0,0 +1,87 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_rep_open(3) +--- +<h1>nng_rep_open(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_rep_open - create rep socket</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/reqrep0/rep.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_rep0_open</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_rep0_open_raw</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_rep0_open()</code> function creates a <a href="nng_rep.7.html"><em>rep</em></a> version 0 +<a href="nng_socket.5.html">socket</a> and returns it at the location pointed to by <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_rep0_open_raw()</code> function creates a <a href="nng_rep.7.html"><em>rep</em></a> version 0 +<a href="nng_socket.5.html">socket</a> +in <a href="nng.7.html#raw_mode">raw</a> mode and returns it at the location pointed to by <em>s</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng_rep.7.html">nng_rep(7)</a>, +<a href="nng_req.7.html">nng_req(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_req.7.html b/man/v1.7.2/nng_req.7.html new file mode 100644 index 00000000..8d193085 --- /dev/null +++ b/man/v1.7.2/nng_req.7.html @@ -0,0 +1,241 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_req(7) +--- +<h1>nng_req(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_req - request protocol</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/reqrep0/req.h></span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>req</em> protocol is one half of a request/reply pattern. +In this pattern, a requester sends a message to one replier, who +is expected to reply. +The request is resent if no reply arrives, +until a reply is received or the request times out.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This protocol is useful in setting up RPC-like services. +It is also "reliable", in that a the requester will keep retrying until +a reply is received. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Because requests are resent, it is important that they be idempotent +to ensure predictable and repeatable behavior even in the face of duplicated +requests, which can occur (for example if a reply message is lost for +some reason.) +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p> +The requester generally only has one outstanding request at a time unless +in raw mode (via +<a href="nng_options.5.html#NNG_OPT_RAW"><code>NNG_OPT_RAW</code></a>), +and it will generally attempt to spread work requests to different peer repliers.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This property, when combined with <a href="nng_device.3.html"><code>nng_device()</code></a> +can help provide a degree of load-balancing. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>req</em> protocol is the requester side, and the +<a href="nng_rep.7.html"><em>rep</em></a> protocol is the replier side.</p> +</div> +<div class="sect2"> +<h3 id="_socket_operations">Socket Operations</h3> +<div class="paragraph"> +<p>The <a href="nng_req_open.3.html"><code>nng_req0_open()</code></a> functions create a requester socket. +This socket may be used to send messages (requests), and then to receive replies.</p> +</div> +<div class="paragraph"> +<p>Generally a reply can only be received after sending a request. +(Attempts to receive a message will result in <code>NNG_ESTATE</code> if there is no +outstanding request.)</p> +</div> +<div class="paragraph"> +<p>Furthermore, only a single receive operation may be pending at a time. +Attempts to post more receive operations concurrently will result in +<code>NNG_ESTATE</code>.</p> +</div> +<div class="paragraph"> +<p>Requests may be canceled by sending a different request. +This will cause the requester to discard any reply from the earlier request, +but it will not stop a replier +from processing a request it has already received or terminate a request +that has already been placed on the wire.</p> +</div> +<div class="paragraph"> +<p><a href="nng.7.html#raw_mode">Raw</a> mode sockets ignore all these restrictions.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_context_operations">Context Operations</h3> +<div class="paragraph"> +<p>This protocol supports the creation of <a href="nng_ctx.5.html">contexts</a> for concurrent +use cases using <a href="nng_ctx_open.3.html"><code>nng_ctx_open()</code></a>.</p> +</div> +<div class="paragraph"> +<p>The <code>NNG_OPT_REQ_RESENDTIME</code> value may be configured differently +on contexts created this way.</p> +</div> +<div class="paragraph"> +<p>Each context may have at most one outstanding request, and operates +independently from the others.</p> +</div> +<div class="paragraph"> +<p>The restrictions for order of operations with sockets apply equally +well for contexts, except that each context will be treated as if it were +a separate socket.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_versions">Protocol Versions</h3> +<div class="paragraph"> +<p>Only version 0 of this protocol is supported. +(At the time of writing, no other versions of this protocol have been defined.)</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_options">Protocol Options</h3> +<div class="paragraph"> +<p>The following protocol-specific option is available.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_REQ_RESENDTIME</code></dt> +<dd> +<p>(<a href="nng_duration.5.html"><code>nng_duration</code></a>) +When a new request is started, a timer of this duration is also started. +If no reply is received before this timer expires, then the request will +be resent.</p> +<div class="paragraph"> +<p>(Requests are also automatically resent if the peer to whom +the original request was sent disconnects, or if a peer becomes available +while the requester is waiting for an available peer.)</p> +</div> +<div class="paragraph"> +<p>Resending may be deferred up to the value of the <code>NNG_OPT_RESENDTICK</code> parameter.</p> +</div> +</dd> +<dt class="hdlist1"><code>NNG_OPT_REQ_RESENDTICK</code></dt> +<dd> +<p>(<a href="nng_duration.5.html"><code>nng_duration</code></a>) +This is the granularity of the clock that is used to check for resending. +The default is a second. Setting this to a higher rate will allow for +more timely resending to occur, but may incur significant additional +overhead when the socket has many outstanding requests (contexts).</p> +<div class="paragraph"> +<p>When there are no requests outstanding that have a resend set, then +the clock does not tick at all.</p> +</div> +<div class="paragraph"> +<p>This option is shared for all contexts on a socket, and is only available for the socket itself.</p> +</div> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_headers">Protocol Headers</h3> +<div class="paragraph"> +<p> +This protocol uses a <em>backtrace</em> in the header. +This form uses a stack of 32-bit big-endian identifiers. +There <strong>must</strong> be at least one identifier, the <em>request ID</em>, which will be the +last element in the array, and <strong>must</strong> have the most significant bit set.</p> +</div> +<div class="paragraph"> +<p>There may be additional <em>peer ID</em>s preceding the request ID. +These will be distinguishable from the request ID by having their most +significant bit clear.</p> +</div> +<div class="paragraph"> +<p>When a request message is received by a forwarding node (see +<a href="nng_device.3.html"><code>nng_device()</code></a>), the forwarding node prepends a +32-bit peer ID (which <strong>must</strong> have the most significant bit clear), +which is the forwarder’s way of identifying the directly connected +peer from which it received the message. +(This peer ID, except for the +most significant bit, has meaning only to the forwarding node itself.)</p> +</div> +<div class="paragraph"> +<p>It may help to think of prepending a peer ID as pushing a peer ID onto the +front of the stack of headers for the message. +(It will use the peer ID +it popped from the front to determine the next intermediate destination +for the reply.)</p> +</div> +<div class="paragraph"> +<p>When a reply message is created, it is created using the same headers +that the request contained.</p> +</div> +<div class="paragraph"> +<p>A forwarding node can pop the peer ID it originally pushed on the +message, stripping it from the front of the message as it does so.</p> +</div> +<div class="paragraph"> +<p>When the reply finally arrives back at the initiating requester, it +should have only a single element in the message, which will be the +request ID it originally used for the request.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_ctx_open.3.html">nng_ctx_open(3)</a>, +<a href="nng_device.3.html">nng_device(3)</a>, +<a href="nng_req_open.3.html">nng_req_open(3)</a>, +<a href="nng_ctx.5.html">nng_ctx(5)</a>, +<a href="nng.7.html">nng(7)</a>, +<a href="nng_rep.7.html">nng_rep(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_req_open.3.html b/man/v1.7.2/nng_req_open.3.html new file mode 100644 index 00000000..d8f10340 --- /dev/null +++ b/man/v1.7.2/nng_req_open.3.html @@ -0,0 +1,89 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_req_open(3) +--- +<h1>nng_req_open(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_req_open - create req socket</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/reqrep0/req.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_req0_open</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_req0_open_raw</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_req0_open()</code> function creates a <a href="nng_req.7.html"><em>req</em></a> version 0 +<a href="nng_socket.5.html">socket</a> and returns it at the location pointed to by <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_req0_open_raw()</code> function creates a <a href="nng_req.7.html"><em>req</em></a> version 0 +<a href="nng_socket.5.html">socket</a> in +<a href="nng.7.html#raw_mode">raw</a> mode +and returns it at the location pointed to by <em>s</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng_rep.7.html">nng_rep(7)</a>, +<a href="nng_req.7.html">nng_req(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_respondent.7.html b/man/v1.7.2/nng_respondent.7.html new file mode 100644 index 00000000..acafd434 --- /dev/null +++ b/man/v1.7.2/nng_respondent.7.html @@ -0,0 +1,123 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_respondent(7) +--- +<h1>nng_respondent(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_respondent - respondent protocol</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/survey0/respond.h></span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>respondent</em> protocol is one half of a survey pattern. +In this pattern, a surveyor sends a survey, which is broadcast to all +peer respondents. +The respondents then have a chance to reply (but are not obliged to reply). +The survey itself is a timed event, so that responses +received after the survey has finished are discarded.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This protocol is useful in solving voting problems, such as leader +election in cluster configurations, as well as certain kinds of service +discovery problems. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>respondent</em> protocol is the respondent side, and the +<a href="nng_surveyor.7.html"><em>surveyor</em></a> protocol is the surveyor side.</p> +</div> +<div class="sect2"> +<h3 id="_socket_operations">Socket Operations</h3> +<div class="paragraph"> +<p>The <a href="nng_respondent_open.3.html"><code>nng_respondent0_open()</code></a> functions create a +respondent socket. +This socket may be used to receive messages, and then to send replies. +A reply can only be sent after receiving a survey, and generally the +reply will be sent to surveyor from whom the last survey was received.</p> +</div> +<div class="paragraph"> +<p>Respondents may discard a survey by simply not replying to it.</p> +</div> +<div class="paragraph"> +<p>Raw mode sockets (set with <a href="nng_options.5.html#NNG_OPT_RAW"><code>NNG_OPT_RAW</code></a>) +ignore all these restrictions.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_context_operations">Context Operations</h3> +<div class="paragraph"> +<p>This protocol supports the creation of <a href="nng_ctx.5.html">contexts</a> for concurrent +use cases using <a href="nng_ctx_open.3.html"><code>nng_ctx_open()</code></a>.</p> +</div> +<div class="paragraph"> +<p>Incoming surveys will be routed to and received by only one context. +Additional surveys may be received by other contexts in parallel. +Replies made using a context will be returned to the the surveyor that +issued the survey most recently received by that context. +The restrictions for order of operations with sockets apply equally +well for contexts, except that each context will be treated as if it were +a separate socket.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_versions">Protocol Versions</h3> +<div class="paragraph"> +<p>Only version 0 of this protocol is supported. +(At the time of writing, no other versions of this protocol have been defined. +An earlier and incompatible version of the protocol was used in older +pre-releases of <a href="http://nanomsg.org">nanomsg</a>, but was not released in any +production version.)</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_options">Protocol Options</h3> +<div class="paragraph"> +<p>The <em>respondent</em> protocol has no protocol-specific options.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_headers">Protocol Headers</h3> +<div class="paragraph"> +<p> +The <em>respondent</em> protocol uses a <em>backtrace</em> in the header. +This is more fully documented in the <a href="nng_surveyor.7.html"><em>surveyor</em></a> manual.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_respondent_open.3.html">nng_respondent_open(3)</a>, +<a href="nng_surveyor.7.html">nng_surveyor(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_respondent_open.3.html b/man/v1.7.2/nng_respondent_open.3.html new file mode 100644 index 00000000..b7d70825 --- /dev/null +++ b/man/v1.7.2/nng_respondent_open.3.html @@ -0,0 +1,90 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_respondent_open(3) +--- +<h1>nng_respondent_open(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_respondent_open - create respondent socket</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/survey0/respond.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_respondent0_open</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_respondent0_open_raw</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_respondent0_open()</code> function creates a +<a href="nng_respondent.7.html"><em>respondent</em></a> +version 0 <a href="nng_socket.5.html">socket</a> and returns it at the location +pointed to by <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_respondent0_open_raw()</code> function creates a +<a href="nng_respondent.7.html"><em>respondent</em></a> +version 0 <a href="nng_socket.5.html">socket</a> in +<a href="nng.7.html#raw_mode">raw</a> mode and returns it at the location pointed to by <em>s</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng_respondent.7.html">nng_respondent(7)</a>, +<a href="nng_surveyor.7.html">nng_surveyor(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_send.3.html b/man/v1.7.2/nng_send.3.html new file mode 100644 index 00000000..88bb37a8 --- /dev/null +++ b/man/v1.7.2/nng_send.3.html @@ -0,0 +1,222 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_send(3) +--- +<h1>nng_send(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_send - send data</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_send</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">data</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_send()</code> function sends a message containing the <em>data</em> of +length <em>size</em> using the <a href="nng_socket.5.html">socket</a> <em>s</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The semantics of what sending a message means vary from protocol to +protocol, so examination of the protocol documentation is encouraged. +(For example, with an <a href="nng_pub.7.html"><em>pub</em></a> socket the data is broadcast, so that +any peers who have a suitable subscription will be able to receive it using +<a href="nng_recv.3.html"><code>nng_recv()</code></a> or a similar function.) +Furthermore, some protocols may not support sending data (such as +<a href="nng_sub.7.html"><em>sub</em></a>) or may require other conditions. +(For example, <a href="nng_rep.7.html"><em>rep</em></a> sockets cannot normally send data, +which are responses to requests, until they have first received a request.) +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>flags</em> may contain either of (or neither of) the following values:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_FLAG_NONBLOCK</code></dt> +<dd> +<p>The function returns immediately, regardless of whether +the socket is able to accept the data or not. If the socket is unable +to accept the data (such as if backpressure exists because the peers +are consuming messages too slowly, or no peer is present), then the +function will return with <code>NNG_EAGAIN</code>. If this flag is not specified, +then the function will block if such a condition exists.</p> +</dd> +<dt class="hdlist1"><code>NNG_FLAG_ALLOC</code></dt> +<dd> +<p>The <em>data</em> was allocated using <a href="nng_alloc.3.html"><code>nng_alloc()</code></a>, or was +obtained from a call to <a href="nng_recv.3.html"><code>nng_recv()</code></a> with +the <code>NNG_FLAG_ALLOC</code> flag. +If this function returns success, then the <em>data</em> is "owned" by the +function, and it will assume responsibility for calling +<a href="nng_free.3.html"><code>nng_free()</code></a> when it is no longer needed. +In the absence of this flag, the <em>data</em> is copied by the implementation +before the function returns to the caller.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The <code>NNG_FLAG_ALLOC</code> flag can be used to reduce data copies, thereby +increasing performance. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Regardless of the presence or absence of <code>NNG_FLAG_NONBLOCK</code>, there may +be queues between the sender and the receiver. +Furthermore, there is no guarantee that the message has actually been delivered. +Finally, with some protocols, the semantic is implicitly <code>NNG_FLAG_NONBLOCK</code>, +such as with <a href="nng_pub.7.html"><em>pub</em></a> sockets, which are best-effort delivery only. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +When using <code>NNG_FLAG_ALLOC</code>, it is important that the value of <em>size</em> +match the actual allocated size of the data. +Using an incorrect size results +in unspecified behavior, which may include heap corruption, program crashes, +or trans-dimensional mutation of the program’s author. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EAGAIN</code> +</td> +<td class="hdlist2"> +<p>The operation would block, but <code>NNG_FLAG_NONBLOCK</code> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid set of <em>flags</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EMSGSIZE</code> +</td> +<td class="hdlist2"> +<p>The value of <em>size</em> is too large.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol for socket <em>s</em> does not support sending.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> cannot send data in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>The operation timed out.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_alloc.3.html">nng_alloc(3)</a>, +<a href="nng_free.3.html">nng_free(3)</a>, +<a href="nng_recv.3.html">nng_recv(3)</a>, +<a href="nng_sendmsg.3.html">nng_sendmsg(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_send_aio.3.html b/man/v1.7.2/nng_send_aio.3.html new file mode 100644 index 00000000..2e15c7b9 --- /dev/null +++ b/man/v1.7.2/nng_send_aio.3.html @@ -0,0 +1,182 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_send_aio(3) +--- +<h1>nng_send_aio(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_send_aio - send message asynchronously</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_send_aio</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_send_aio()</code> sends a <a href="nng_msg.5.html">message</a> using the +<a href="nng_socket.5.html">socket</a> <em>s</em> asynchronously.</p> +</div> +<div class="paragraph"> +<p>The message to send must have previously been set on the <em>aio</em> +using the <a href="nng_aio_set_msg.3.html"><code>nng_aio_set_msg()</code></a> function. +The function assumes ownership of the message.</p> +</div> +<div class="paragraph"> +<p>If the message was successfully queued for delivery to the socket, +then the <em>aio</em> will be completed, and <a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a> +will return zero. In this case the socket will dispose of the +message when it is finished with it.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The operation will be completed, and the callback associated +with the <em>aio</em> executed, as soon as the socket accepts the message +for sending. +This does <em>not</em> indicate that the message was actually delivered, as it +may still be buffered in the sending socket, buffered in the receiving +socket, or in flight over physical media. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>If the operation fails for any reason (including cancellation or timeout), +then the <em>aio</em> callback will be executed and +<a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a> +will return a non-zero error status. +In this case, the callback has a responsibility to retrieve the message from +the <em>aio</em> with +<a href="nng_aio_get_msg.3.html"><code>nng_aio_get_msg()</code></a> and dispose of it appropriately. +(This may include retrying the send operation on the same or a different +socket, or deallocating the message with <a href="nng_msg_free.3.html"><code>nng_msg_free()</code></a>.)</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The semantics of what sending a message means varies from protocol to +protocol, so examination of the protocol documentation is encouraged. +(For example, with a <a href="nng_pub.7.html"><em>pub</em></a> socket the data is broadcast, so that +any peers who have a suitable subscription will be able to receive it using +<a href="nng_recv.3.html"><code>nng_recv()</code></a> or a similar function.) +Furthermore, some protocols may not support sending (such as +<a href="nng_sub.7.html"><em>sub</em></a>) or may require other conditions. +(For example, <a href="nng_rep.7.html"><em>rep</em></a> sockets cannot normally send data, which +are responses to requests, until they have first received a request.) +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None. (The operation completes asynchronously.)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was aborted.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EMSGSIZE</code> +</td> +<td class="hdlist2"> +<p>The message is too large.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol for socket <em>s</em> does not support sending.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> cannot send data in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>The send timeout expired.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_get_msg.3.html">nng_aio_get_msg(3)</a>, +<a href="nng_aio_set_msg.3.html">nng_aio_set_msg(3)</a>, +<a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_sendmsg.3.html b/man/v1.7.2/nng_sendmsg.3.html new file mode 100644 index 00000000..05b779cc --- /dev/null +++ b/man/v1.7.2/nng_sendmsg.3.html @@ -0,0 +1,206 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_sendmsg(3) +--- +<h1>nng_sendmsg(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_sendmsg - send message</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_sendmsg</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_msg</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">msg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">flags</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_sendmsg()</code> sends message <em>msg</em> using the socket <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>If the function returns zero, indicating it has accepted the message for +delivery, then the <em>msg</em> is owned by the socket <em>s</em>, and the caller +must not make any further use of it. +The socket will free the message when it is finished.</p> +</div> +<div class="paragraph"> +<p>If the function returns non-zero, then it is the caller’s responsibility +to dispose of the <em>msg</em>, which may include freeing it, sending it to +another socket, or simply trying again later.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Using this function gives access to the message structure, and may +offer more functionality than the simpler <a href="nng_send.3.html"><code>nng_send()</code></a> function. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The semantics of what sending a message means vary from protocol to +protocol, so examination of the protocol documentation is encouraged. +(For example, with a <a href="nng_pub.7.html"><em>pub</em></a> socket the data is broadcast, so that +any peers who have a suitable subscription will be able to receive it using +<a href="nng_recv.3.html"><code>nng_recv()</code></a> or a similar function.) +Furthermore, some protocols may not support sending (such as +<a href="nng_sub.7.html"><em>sub</em></a>) or may require other conditions. +(For example, <a href="nng_rep.7.html"><em>rep</em></a> sockets cannot normally send data, which +are responses to requests, until they have first received a request.) +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>flags</em> may contain the following value:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_FLAG_NONBLOCK</code></dt> +<dd> +<p>The function returns immediately, regardless of whether +the socket is able to accept the data or not. +If the socket is unable to accept the data (such as if backpressure exists +because the peers are consuming messages too slowly, or no peer is present), +then the function will return with <code>NNG_EAGAIN</code>. +If this flag is not specified, then the function will block if such a +condition exists.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Regardless of the presence or absence of <code>NNG_FLAG_NONBLOCK</code>, there may +be queues between the sender and the receiver. +Furthermore, there is no guarantee that the message has actually been delivered. +Finally, with some protocols, the semantic is implicitly <code>NNG_FLAG_NONBLOCK</code>, +such as with <a href="nng_pub.7.html"><em>pub</em></a> sockets, which are best-effort delivery only. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EAGAIN</code> +</td> +<td class="hdlist2"> +<p>The operation would block, but <code>NNG_FLAG_NONBLOCK</code> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> is not open.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid set of <em>flags</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EMSGSIZE</code> +</td> +<td class="hdlist2"> +<p>The value of <em>size</em> is too large.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol for socket <em>s</em> does not support sending.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The socket <em>s</em> cannot send data in this state.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>The operation timed out.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_msg_alloc.3.html">nng_msg_alloc(3)</a>, +<a href="nng_recvmsg.3.html">nng_recvmsg(3)</a>, +<a href="nng_send.3.html">nng_send(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_setopt.3.html b/man/v1.7.2/nng_setopt.3.html new file mode 100644 index 00000000..9954c9da --- /dev/null +++ b/man/v1.7.2/nng_setopt.3.html @@ -0,0 +1,234 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_setopt(3) +--- +<h1>nng_setopt(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_setopt - set socket option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_setopt</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">valsz</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_setopt_bool</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">bval</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_setopt_int</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">ival</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_setopt_ms</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">dur</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_setopt_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_setopt_size</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">z</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_setopt_string</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">str</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_setopt_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">u64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +These functions are deprecated. Please see <a href="nng_socket_set.3.html">nng_socket_set</a>. +They may not be present if the library was built with <code>NNG_ELIDE_DEPRECATED</code>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p> +The <code>nng_setopt()</code> functions are used to configure options for +the socket <em>s</em>. +The actual options that may be configured in this way vary, and are +specified by <em>opt</em>. +A number of them are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally some transport-specific and protocol-specific options are +documented with the transports and protocols themselves.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_setopt()</code></dt> +<dd> +<p>This function is untyped, and can be used to configure any arbitrary data. +The <em>val</em> pointer addresses the data to copy, and <em>valsz</em> is the +size of the objected located at <em>val</em>.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_setopt_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The <em>bval</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_setopt_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The <em>ival</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_setopt_ms()</code></dt> +<dd> +<p>This function is used to configure time durations (such as timeouts) using +type <a href="nng_duration.5.html"><code>nng_duration</code></a>. +The duration <em>dur</em> is an integer number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_setopt_ptr()</code></dt> +<dd> +<p>This function is used to pass a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed by other functions. +For example, TLS configuration objects created with +(<a href="nng_tls_config_alloc.3tls.html"><code>nng_tls_config_alloc()</code></a>) +can be passed this way.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_setopt_size()</code></dt> +<dd> +<p>This function is used to configure a size, <em>z</em>, typically for buffer sizes, +message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_setopt_string()</code></dt> +<dd> +<p>This function is used to pass configure a string, <em>str</em>. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a <code>NUL</code> (<code>\0</code>) byte. +(Other constraints may apply as well, see the documentation for each option +for details.)</p> +</dd> +<dt class="hdlist1"><code>nng_setopt_uint64()</code></dt> +<dd> +<p>This function is used to configure a 64-bit unsigned value, <em>u64</em>. +This is typically used for options related to identifiers, network numbers, +and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>s</em> does not refer to an open socket.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The value being passed is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EREADONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is read-only.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The socket is in an inappropriate state for setting this option.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_getopt.3.html">nng_getopt(3)</a>, +<a href="nng_dialer_setopt.3.html">nng_dialer_setopt(3)</a>, +<a href="nng_listener_setopt.3.html">nng_listener_setopt(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_sleep_aio.3.html b/man/v1.7.2/nng_sleep_aio.3.html new file mode 100644 index 00000000..a4b63ae2 --- /dev/null +++ b/man/v1.7.2/nng_sleep_aio.3.html @@ -0,0 +1,81 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_sleep_aio(3) +--- +<h1>nng_sleep_aio(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_sleep_aio - sleep asynchronously</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_sleep_aio</span><span class="tok-p">(</span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">msec</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_sleep_aio()</code> function provides an asynchronous delay mechanism, +causing the callback for <em>aio</em> to be executed after <em>msec</em> milliseconds. +If the sleep finishes completely, the result will always be zero.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +If a timeout is set on <em>aio</em> using +<a href="nng_aio_set_timeout.3.html"><code>nng_aio_set_timeout()</code></a>, and it is shorter +than <em>msec</em>, +then the sleep will wake up early, with a result code of <code>NNG_ETIMEDOUT</code>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_abort.3.html">nng_aio_abort(3)</a>, +<a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_set_timeout.3.html">nng_aio_set_timeout(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_sockaddr.5.html b/man/v1.7.2/nng_sockaddr.5.html new file mode 100644 index 00000000..273c4cf6 --- /dev/null +++ b/man/v1.7.2/nng_sockaddr.5.html @@ -0,0 +1,156 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_sockaddr(5) +--- +<h1>nng_sockaddr(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_sockaddr - socket address</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">union</span><span class="tok-w"> </span><span class="tok-nc">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">s_family</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_sockaddr_ipc</span><span class="tok-w"> </span><span class="tok-n">s_ipc</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_sockaddr_inproc</span><span class="tok-w"> </span><span class="tok-n">s_inproc</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_sockaddr_in</span><span class="tok-w"> </span><span class="tok-n">s_in</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_sockaddr_in6</span><span class="tok-w"> </span><span class="tok-n">s_in6</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_sockaddr_zt</span><span class="tok-w"> </span><span class="tok-n">s_zt</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-n">nng_sockaddr_abstract</span><span class="tok-w"> </span><span class="tok-n">s_abstract</span><span class="tok-p">;</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-p">;</span> + +<span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-n">sockaddr_family</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_UNSPEC</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">0</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_INPROC</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">1</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_IPC</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">2</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_INET</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">3</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_INET6</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">4</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_ZT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">5</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_ABSTRACT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">6</span> +<span class="tok-p">};</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +An <code>nng_sockaddr</code> is a structure used for +representing the addresses used by underlying transports, such as TCP/IP +addresses, IPC paths, and so forth.</p> +</div> +<div class="sidebarblock"> +<div class="content"> +<div class="paragraph"> +<p>The name <code>sockaddr</code> is based on its similarity with POSIX <code>struct sockaddr</code>, +but in <em>NNG</em>, these addresses are more closely affiliated with +instances of <a href="nng_pipe.5.html"><code>nng_pipe</code></a> +than of <a href="nng_socket.5.html"><code>nng_socket</code></a>. +The naming confusion is unfortunate.</p> +</div> +</div> +</div> +<div class="paragraph"> +<p>This structure is actually a union, with different members for different +types of addresses.</p> +</div> +<div class="paragraph"> +<p>Every member structure has as its first element a <code>uint16_t</code> field +containing the address family. +This overlaps the <code>s_family</code> member of the union, and indicates which +specific member should be used.</p> +</div> +<div class="paragraph"> +<p>The values of <code>s_family</code> are as follows:</p> +</div> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_AF_UNSPEC</code> +</td> +<td class="hdlist2"> +<p>Invalid address, no other valid fields.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_AF_INPROC</code> +</td> +<td class="hdlist2"> +<p>Address for intraprocess communication (<a href="nng_inproc.7.html">nng_inproc(7)</a>). The <code>s_inproc</code> member is valid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_AF_IPC</code> +</td> +<td class="hdlist2"> +<p>Address for interprocess communication (<a href="nng_ipc.7.html">nng_ipc(7)</a>). The <code>s_path</code> member is valid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_AF_INET</code> +</td> +<td class="hdlist2"> +<p>Address for TCP/IP (v4) communication. The <code>s_in</code> member is valid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_AF_INET6</code> +</td> +<td class="hdlist2"> +<p>Address for TCP/IP (v6) communication. The <code>s_in6</code> member is valid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_AF_ZT</code> +</td> +<td class="hdlist2"> +<p>Address for ZeroTier transport (<a href="nng_zerotier.7.html">nng_zerotier(7)</a>). The <code>s_zt</code> member is valid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_AF_ABSTRACT</code> +</td> +<td class="hdlist2"> +<p>Address for an abstract UNIX domain socket. The <code>s_abstract</code> member is valid.</p> +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Please see the manual pages for each individual type for more information.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sockaddr_abstract.5.html">nng_sockaddr_abstract(5)</a>, +<a href="nng_sockaddr_in.5.html">nng_sockaddr_in(5)</a>, +<a href="nng_sockaddr_in6.5.html">nng_sockaddr_in6(5)</a>, +<a href="nng_sockaddr_inproc.5.html">nng_sockaddr_inproc(5)</a>, +<a href="nng_sockaddr_ipc.5.html">nng_sockaddr_ipc(5)</a>, +<a href="nng_sockaddr_zt.5.html">nng_sockaddr_zt(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_sockaddr_abstract.5.html b/man/v1.7.2/nng_sockaddr_abstract.5.html new file mode 100644 index 00000000..b657ea0f --- /dev/null +++ b/man/v1.7.2/nng_sockaddr_abstract.5.html @@ -0,0 +1,128 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_sockaddr_abstract(5) +--- +<h1>nng_sockaddr_abstract(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_sockaddr_abstract - abstract IPC socket address</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-n">sockaddr_family</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_ABSTRACT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">6</span><span class="tok-p">,</span> +<span class="tok-p">};</span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">sa_family</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">sa_len</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-n">sa_name</span><span class="tok-p">[</span><span class="tok-mi">107</span><span class="tok-p">];</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr_abstract</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> An <code>nng_sockaddr_abstract</code> is the flavor of <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +used to represent addresses associated with IPC communication using “abstract” sockets.</p> +</div> +<div class="paragraph"> +<p>Abstract sockets are only supported on Linux at present. +These sockets have a name that is simply an array of bytes, with no special meaning. +Abstract sockets also have no presence in the file system, do not honor any permissions, and are automatically +cleaned up by the operating system when no longer in use.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Support for abstract sockets is a new feature in <em>NNG</em>, and it is only available on Linux. +As such their use is not recommended for portable applications. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The following structure members are present:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>sa_family</code></dt> +<dd> +<p>This field will always have the value <code>NNG_AF_ABSTRACT</code>.</p> +</dd> +<dt class="hdlist1"><code>sa_len</code></dt> +<dd> +<p>This field provides the name of the length stored in <code>sa_name</code>.</p> +</dd> +<dt class="hdlist1"><code>sa_name</code></dt> +<dd> +<p>This field holds the name of the abstract socket. +The bytes of name can have any value, including zero.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The name does <em>not</em> include the leading <code>NUL</code> byte used on Linux to discriminate between +abstract and path name sockets. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_auto_bind">Auto Bind</h3> +<div class="paragraph"> +<p>An empty value (<code>sa_len</code> equal to zero) can be used on listening sockets to request the +system allocate a name. +On Linux systems, this will result in a name with either 5 or 8 hexadecimal ASCII characters. +The name chosen can be obtained by retrieving the <code>NNG_OPT_LOCADDR</code> option on the listening entity.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Because a zero length name is used to indicate auto bind be used, it is impossible to specify +an actual empty name. This name are not supported by <em>NNG</em>, although the underlying system can support it. +The use of that name is inadvisable anyway. +</td> +</tr> +</table> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng_ipc.7.html">nng_ipc(7)</a> +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_sockaddr_in.5.html b/man/v1.7.2/nng_sockaddr_in.5.html new file mode 100644 index 00000000..9b10d654 --- /dev/null +++ b/man/v1.7.2/nng_sockaddr_in.5.html @@ -0,0 +1,110 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_sockaddr_in(5) +--- +<h1>nng_sockaddr_in(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_sockaddr_in - IPv4 socket address</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-n">sockaddr_family</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_INET</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">3</span><span class="tok-p">,</span> +<span class="tok-p">};</span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">sa_family</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">sa_port</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">uint32_t</span><span class="tok-w"> </span><span class="tok-n">sa_addr</span><span class="tok-p">;</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr_in</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +An <code>nng_sockaddr_in</code> is the flavor of <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +used to represent TCP (and sometimes UDP) addresses, +including the Internet Protocol (IP) address and port number.</p> +</div> +<div class="paragraph"> +<p>This structure is used with IPv4 addresses. +A different structure, <a href="nng_sockaddr_in6.5.html"><code>nng_sockaddr_in6</code></a>, is used +for IPv6 addresses.</p> +</div> +<div class="paragraph"> +<p>The following structure members are present:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>sa_family</code></dt> +<dd> +<p>This field will always have the value <code>NNG_AF_INET</code>.</p> +</dd> +<dt class="hdlist1"><code>sa_port</code></dt> +<dd> +<p>This field holds the TCP or UDP port number, in network byte-order. +A zero value here is used when no specific port number is indicated.</p> +</dd> +<dt class="hdlist1"><code>sa_addr</code></dt> +<dd> +<p>This field holds the IP address in +network-byte order.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The <code>sa_port</code> and <code>sa_addr</code> fields are in network-byte order to +facilitate their use with system APIs such as <code>inet_ntop()</code>. +Most platforms use some form of BSD-derived network API, which uses +network-byte order in the various structures (such as <code>sockaddr_in</code>). +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This field appears similar to BSD <code>sockaddr_in</code>, but it is +<em>not</em> the same, and they may not be used interchangeably. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng_sockaddr_in6.5.html">nng_sockaddr_in6(5)</a>, +<a href="nng_tcp.7.html">nng_tcp(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_sockaddr_in6.5.html b/man/v1.7.2/nng_sockaddr_in6.5.html new file mode 100644 index 00000000..c8717dac --- /dev/null +++ b/man/v1.7.2/nng_sockaddr_in6.5.html @@ -0,0 +1,119 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_sockaddr_in6(5) +--- +<h1>nng_sockaddr_in6(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_sockaddr_in6 - IPv6 socket address</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-n">sockaddr_family</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_INET6</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">4</span><span class="tok-p">,</span> +<span class="tok-p">};</span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">sa_family</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">sa_port</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">uint8_t</span><span class="tok-w"> </span><span class="tok-n">sa_addr</span><span class="tok-p">[</span><span class="tok-mi">16</span><span class="tok-p">];</span> +<span class="tok-w"> </span><span class="tok-kt">uint32_t</span><span class="tok-w"> </span><span class="tok-n">sa_scope</span><span class="tok-p">;</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr_in6</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +An <code>nng_sockaddr_in6</code> is the flavor of <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +used to represent TCP (and sometimes UDP) addresses, +including the Internet Protocol (IP) address and port number.</p> +</div> +<div class="paragraph"> +<p>This structure is used with IPv6 addresses. +A different structure, <a href="nng_sockaddr_in.5.html"><code>nng_sockaddr_in</code></a>, is used +for IPv4 addresses.</p> +</div> +<div class="paragraph"> +<p>The following structure members are present:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>sa_family</code></dt> +<dd> +<p>This field will always have the value <code>NNG_AF_INET6</code>.</p> +</dd> +<dt class="hdlist1"><code>sa_port</code></dt> +<dd> +<p>This field holds the TCP or UDP port number, in network byte-order. +A zero value here is used when no specific port number is indicated.</p> +</dd> +<dt class="hdlist1"><code>sa_addr</code></dt> +<dd> +<p>This field holds the IP address in +network-byte order.</p> +</dd> +<dt class="hdlist1"><code>sa_scope</code></dt> +<dd> +<p>This is the scope, and is typically used with link local +addresses to identify a specific interface. The details of +this are specific to the operating system. This value is +presented identically to the underlying system’s, including +any byte order considerations.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The <code>sa_port</code> and <code>sa_addr</code> fields are in network-byte order to +facilitate their use with system APIs such as <code>inet_ntop()</code>. +Most platforms use some form of BSD-derived network API, which uses +network-byte order in the various structures (such as <code>sockaddr_in6</code>). +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This field appears similar to BSD <code>sockaddr_in6</code>, but it is +<em>not</em> the same, and they may not be used interchangeably. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng_sockaddr_in.5.html">nng_sockaddr_in(5)</a>, +<a href="nng_tcp.7.html">nng_tcp(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_sockaddr_inproc.5.html b/man/v1.7.2/nng_sockaddr_inproc.5.html new file mode 100644 index 00000000..56556276 --- /dev/null +++ b/man/v1.7.2/nng_sockaddr_inproc.5.html @@ -0,0 +1,85 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_sockaddr_inproc(5) +--- +<h1>nng_sockaddr_inproc(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_sockaddr_inproc - inproc socket address</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-n">sockaddr_family</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_INPROC</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">1</span><span class="tok-p">,</span> +<span class="tok-p">};</span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">sa_family</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">sa_name</span><span class="tok-p">[</span><span class="tok-mi">128</span><span class="tok-p">];</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr_inproc</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +An <code>nng_sockaddr_inproc</code> is the flavor of <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +used to represent addresses associated with intra-process communication +using the <a href="nng_inproc.7.html"><em>inproc</em></a> transport.</p> +</div> +<div class="paragraph"> +<p>The following structure members are present:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>sa_family</code></dt> +<dd> +<p>This field will always have the value <code>NNG_AF_INPROC</code>.</p> +</dd> +<dt class="hdlist1"><code>sa_name</code></dt> +<dd> +<p>This field holds an arbitrary C string, which is the name of the address. +The string must be <code>NUL</code> terminated, but no other restrictions exist.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +In order to ensure maximum compatibility, applications should avoid +hard coding the size of the <code>sa_name</code> member explicitly, but use the +<code>sizeof</code> operator to determine its actual size at compile time. +Furthermore, the size is guaranteed to be at least 128. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng_inproc.7.html">nng_inproc(7)</a> +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_sockaddr_ipc.5.html b/man/v1.7.2/nng_sockaddr_ipc.5.html new file mode 100644 index 00000000..80a03235 --- /dev/null +++ b/man/v1.7.2/nng_sockaddr_ipc.5.html @@ -0,0 +1,122 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_sockaddr_ipc(5) +--- +<h1>nng_sockaddr_ipc(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_sockaddr_ipc - IPC socket address</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-n">sockaddr_family</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_IPC</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">2</span><span class="tok-p">,</span> +<span class="tok-p">};</span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">sa_family</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-n">sa_path</span><span class="tok-p">[</span><span class="tok-mi">128</span><span class="tok-p">];</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr_ipc</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> An <code>nng_sockaddr_ipc</code> is the flavor of <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +used to represent addresses associated with IPC communication using the <a href="nng_ipc.7.html"><em>ipc</em></a> transport.</p> +</div> +<div class="paragraph"> +<p>The following structure members are present:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>sa_family</code></dt> +<dd> +<p>This field will always have the value <code>NNG_AF_IPC</code>.</p> +</dd> +<dt class="hdlist1"><code>sa_path</code></dt> +<dd> +<p>This field holds the C string corresponding to path name where the IPC socket is located. +For systems using UNIX domain sockets, this will be a path name in the file system, where the UNIX domain socket is located. +For Windows systems, this is the path name of the Named Pipe, without the leading <code>\\.pipe\</code> portion, which will be automatically added.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +At this time, there is no support for abstract sockets. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +In order to ensure maximum compatibility, applications should avoid hard coding the size of the <code>sa_path</code> member explicitly, but use the +<code>sizeof</code> operator to determine its actual size at compile time. +Furthermore, the size is guaranteed to be at least 128, but paths of this length may not be supported on all systems. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Portable applications should restrict themselves to path names of not more than 90 bytes. Most systems have +limits around 100 bytes, but at least one system (HP-UX) is restricted to not more than 92 bytes including the <code>NUL</code>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +If compatibility with legacy <em>nanomsg</em> applications is required, then path names must not be longer than 122 bytes, including the final +<code>NUL</code> byte. +This is because legacy versions of <em>nanomsg</em> cannot express URLs longer than 128 bytes, including the <code>ipc://</code> prefix. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng_ipc.7.html">nng_ipc(7)</a> +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_sockaddr_zt.5.html b/man/v1.7.2/nng_sockaddr_zt.5.html new file mode 100644 index 00000000..a96b0875 --- /dev/null +++ b/man/v1.7.2/nng_sockaddr_zt.5.html @@ -0,0 +1,121 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_sockaddr_zt(5) +--- +<h1>nng_sockaddr_zt(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_sockaddr_zt - ZeroTier socket address</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-n">sockaddr_family</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_AF_ZT</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mi">5</span><span class="tok-p">,</span> +<span class="tok-p">};</span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">uint16_t</span><span class="tok-w"> </span><span class="tok-n">sa_family</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">sa_nwid</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">sa_nodeid</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">uint32_t</span><span class="tok-w"> </span><span class="tok-n">sa_port</span><span class="tok-p">;</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr_zt</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +An <code>nng_sockaddr_zt</code> is the flavor of <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> +used to represent ZeroTier addresses, including the +port number used by the +<a href="nng_zerotier.7.html"><em>zt</em></a> transport.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +The ZeroTier transport, and the details of this structure, +are still considered experimental, and subject to change. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The following structure members are present:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>sa_family</code></dt> +<dd> +<p>This field will always have the value <code>NNG_AF_ZT</code>.</p> +</dd> +<dt class="hdlist1"><code>sa_nwid</code></dt> +<dd> +<p> +This field holds the ZeroTier network number (or ID). +This value is in native byte order.</p> +</dd> +<dt class="hdlist1"><code>sa_nodeid</code></dt> +<dd> +<p>This field holds the ZeroTier node ID. +This value is in native byte order, and only the lower 40 bits +are significant. +(ZeroTier node numbers are 40 bits long.) +A zero value here is used for a wild-card to indicate that the +caller’s own node number be used.</p> +</dd> +<dt class="hdlist1"><code>sa_port</code></dt> +<dd> +<p>This field holds the port number used by the +<a href="nng_zerotier.7.html"><em>zt</em></a> transport to distinguish different +sockets. +This value in native byte order. +A zero value here indicates that a port number should be chosen +randomly from the ephemeral ports. +Only the lower 24 bits of the port number are used.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +ZeroTier port numbers are in <strong>native</strong> byte order, and are larger +than TCP/IP port numbers. +They are also not part of the ZeroTier protocol itself, but defined by +the Scalability Protocols binding for them. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng_zerotier.7.html">nng_zerotier(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_socket.5.html b/man/v1.7.2/nng_socket.5.html new file mode 100644 index 00000000..b5b1da60 --- /dev/null +++ b/man/v1.7.2/nng_socket.5.html @@ -0,0 +1,94 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_socket(5) +--- +<h1>nng_socket(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_socket - socket handle</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_socket_s</span><span class="tok-w"> </span><span class="tok-n">nng_socket</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>An <code>nng_socket</code> is a handle to an underlying socket object. +All communication between the application and remote Scalability Protocol +peers is done through sockets. +A given socket can have multiple dialers (<a href="nng_dialer.5.html"><code>nng_dialer</code></a>) +and/or listeners (<a href="nng_listener.5.html"><code>nng_listener</code></a>), and multiple +pipes (<a href="nng_pipe.5.html"><code>nng_pipe</code></a>), and +may be connected to multiple transports at the same time. +However, a given socket will have exactly one protocol associated with it, +and is responsible for any state machines or other protocol-specific logic.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +The <code>nng_socket</code> structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way gives the compiler a chance to perform +accurate type checks in functions passing values of this type. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Each <code>nng_socket</code> is created by a protocol-specific constructor, such as +<a href="nng_rep_open.3.html"><code>nng_rep_open()</code></a>. +When the socket is no longer needed, it can be closed with +<a href="nng_close.3.html"><code>nng_close()</code></a>.</p> +</div> +<div class="sect2"> +<h3 id="NNG_SOCKET_INITIALIZER">Initialization</h3> +<div class="paragraph"> +<p>A socket may be initialized using the macro <code>NNG_SOCKET_INITIALIZER</code> +before it is opened, to prevent confusion with valid open sockets.</p> +</div> +<div class="paragraph"> +<p>For example:</p> +</div> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-n">NNG_SOCKET_INITIALIZER</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_close.3.html">nng_close(3)</a>, +<a href="nng_getopt.3.html">nng_getopt(3)</a>, +<a href="nng_setopt.3.html">nng_setopt(3)</a>, +<a href="nng_socket_id.3.html">nng_socket_id(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_socket.7.html b/man/v1.7.2/nng_socket.7.html new file mode 100644 index 00000000..2af89ac3 --- /dev/null +++ b/man/v1.7.2/nng_socket.7.html @@ -0,0 +1,129 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_socket(7) +--- +<h1>nng_socket(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_socket - BSD Socket transport (experimental)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>socket</em> transport provides communication support between +peers across a arbitrary BSD sockets, such as those that are +created with <a href="nng_socket_pair.3supp.html"><code>nng_socket_pair()</code></a>.</p> +</div> +<div class="paragraph"> +<p>This transport only supports <a href="nng_listener.5.html">listeners</a>, using <a href="nng_listener_create.3.html"><code>nng_listener_create()</code></a>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Attempts to create a <a href="nng_dialer.5.html">dialer</a> using this transport will result in <code>NNG_ENOTSUP</code>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The socket file descriptor is passed to the listener using the <code>NNG_OPT_SOCKET_FD</code> option (as an integer). +Setting this option (which is read-only and can be set multiple times) will cause the listener +to create a <a href="nng_pipe.5.html">pipe</a> associated backed by the file descriptor.</p> +</div> +<div class="paragraph"> +<p>The protocol between peers using this pipe is at present compatible with the protocol used for the +<a href="nng_tcp.7.html">TCP</a> transport, but this is an implementation detail and subject to change without notice.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This transport is <strong>experimental</strong>, and at present is only supported on POSIX platforms. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_registration">Registration</h3> +<div class="paragraph"> +<p>No special action is necessary to register this transport.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_uri_format">URI Format</h3> +<div class="paragraph"> +<p> +This transport uses the URL <code>socket://</code>, without further qualification.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_socket_address">Socket Address</h3> +<div class="paragraph"> +<p>The socket address will be of family <code>NNG_AF_UNSPEC</code>. +There are no further socket details available.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_transport_options">Transport Options</h3> +<div class="paragraph"> +<p>The following transport option is available:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_SOCKET_FD</code></dt> +<dd> +<p>(int) This is a write-only option, that may be set multiple times on a listener. +The listener will create a pipe backed by the given file descriptor passed as an argument.</p> +</dd> +</dl> +</div> +<div class="paragraph"> +<p>Additionally, the following options may be supported on pipes when the platform supports them:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><a href="nng_options.5.html#NNG_OPT_PEER_GID"><code>NNG_OPT_PEER_GID</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_PEER_PID"><code>NNG_OPT_PEER_PID</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_PEER_UID"><code>NNG_OPT_PEER_UID</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_PEER_ZONEID"><code>NNG_OPT_PEER_ZONEID</code></a></p> +</li> +</ul> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket_pair.3supp.html">nng_socket_pair(3)</a>, +<a href="nng_dialer.5.html">nng_dialer(5)</a>, +<a href="nng_listener.5.html">nng_listener(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_pipe.5.html">nng_pipe(5)</a>, +<a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_socket_get.3.html b/man/v1.7.2/nng_socket_get.3.html new file mode 100644 index 00000000..0102da70 --- /dev/null +++ b/man/v1.7.2/nng_socket_get.3.html @@ -0,0 +1,246 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_socket_get(3) +--- +<h1>nng_socket_get(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_socket_get - get socket option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_get</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valszp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_get_bool</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">bvalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_get_int</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ivalp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_get_size</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">zp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_get_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u64p</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_get_string</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">strp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_get_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_get_ms</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">durp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_get_addr</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">addrp</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <code>nng_socket_get()</code> functions are used to retrieve option values for +the <a href="nng_socket.5.html">socket</a> <em>s</em>. +The actual options that may be retrieved in this way vary. +A number of them are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally protocol-specific options are documented with the protocols themselves.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Access to transport options via this function is deprecated, and may be +removed from a future release. Applications should instead make use of +<a href="nng_dialer_get.3.html">nng_dialer_get</a> or +<a href="nng_listener_get.3.html">nng_listener_get</a> for specific dialers or listeners. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the socket <em>s</em>. +The forms vary based on the type of the option they take.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_socket_get()</code></dt> +<dd> +<p>This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in <em>val</em>, +and the size of the buffer shall be stored at the location referenced by +<em>valszp</em>.</p> +<div class="paragraph"> +<p>When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>valszp</em>. +If the caller’s buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in <em>valszp</em> does not exceed the original buffer size.</p> +</div> +<div class="paragraph"> +<p>It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>valszp</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_socket_get_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The value will be stored at <em>bvalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_socket_get_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The value will be stored at <em>ivalp</em>.</p> +</dd> +<dt class="hdlist1"><code>nng_socket_get_ms()</code></dt> +<dd> +<p>This function is used to retrieve time <a href="nng_duration.5.html">durations</a> +(such as timeouts), stored in <em>durp</em> as a number of milliseconds. +(The special value <code>NNG_DURATION_INFINITE</code> means an infinite amount of time, and +the special value <code>NNG_DURATION_DEFAULT</code> means a context-specific default.)</p> +</dd> +<dt class="hdlist1"><code>nng_socket_get_ptr()</code></dt> +<dd> +<p>This function is used to retrieve a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied.</p> +</dd> +<dt class="hdlist1"><code>nng_socket_get_size()</code></dt> +<dd> +<p>This function is used to retrieve a size into the pointer <em>zp</em>, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_socket_get_string()</code></dt> +<dd> +<p>This function is used to retrieve a string into <em>strp</em>. +This string is created from the source using <a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_socket_get_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value into the value +referenced by <em>u64p</em>. +This is typically used for options related to identifiers, network +numbers, and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EBADTYPE</code> +</td> +<td class="hdlist2"> +<p>Incorrect type for option.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>s</em> does not refer to an open socket.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Size of destination <em>val</em> too small for object.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is write-only.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_dialer_get.3.html">nng_dialer_get(3)</a>, +<a href="nng_listener_get.3.html">nng_listener_get(3)</a>, +<a href="nng_pipe_get.3.html">nng_pipe_get(3)</a>, +<a href="nng_socket_set.3.html">nng_socket_set(3)</a>, +<a href="nng_strdup.3.html">nng_strdup(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_strfree.3.html">nng_strfree(3)</a>, +<a href="nng_duration.5.html">nng_duration(5)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_socket_id.3.html b/man/v1.7.2/nng_socket_id.3.html new file mode 100644 index 00000000..588ffa26 --- /dev/null +++ b/man/v1.7.2/nng_socket_id.3.html @@ -0,0 +1,79 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_socket_id(3) +--- +<h1>nng_socket_id(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_socket_id - return numeric socket identifier</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_id</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_socket_id()</code> function returns a positive identifier for the socket <em>s</em>, +if it is valid. +Otherwise it returns <code>-1</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +A socket is considered valid if it was ever opened with a protocol +constructor, such as the <a href="nng_req_open.3.html"><code>nng_req0_open()</code></a> function. +Sockets that are allocated on the stack or statically should be +initialized with the macro +<a href="nng_socket.5.html#NNG_SOCKET_INITIALIZER"><code>NNG_SOCKET_INITIALIZER</code></a> +to ensure that they cannot be confused with a valid socket before they are opened. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the positive value for the socket identifier, or +<code>-1</code> if the socket is invalid.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_socket_pair.3supp.html b/man/v1.7.2/nng_socket_pair.3supp.html new file mode 100644 index 00000000..fe44849b --- /dev/null +++ b/man/v1.7.2/nng_socket_pair.3supp.html @@ -0,0 +1,108 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_socket_pair(3supp) +--- +<h1>nng_socket_pair(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_socket_pair - create a connected pair of BSD sockets</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_pair</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">fds</span><span class="tok-p">[</span><span class="tok-mi">2</span><span class="tok-p">]);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_socket_pair()</code> function creates a pair of connected BSD sockets. +These sockets, which are returned in the <em>fds</em> array, are suitable for +use with the <a href="nng_socket.7.html"><em>socket</em></a> transport.</p> +</div> +<div class="paragraph"> +<p>On POSIX platforms, this is a thin wrapper around the standard <code>socketpair()</code> function, +using the <code>AF_UNIX</code> family and the <code>SOCK_STREAM</code> socket type.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +At present only POSIX platforms implementing <code>socketpair()</code> are supported with this function. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This function may be useful for creating a shared connection between a parent process and +a child process on UNIX platforms, without requiring the processes use a shared filesystem or TCP connection. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>This platform does not support socket pairs.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.7.html">nng_socket(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_socket_set.3.html b/man/v1.7.2/nng_socket_set.3.html new file mode 100644 index 00000000..d0ee13e2 --- /dev/null +++ b/man/v1.7.2/nng_socket_set.3.html @@ -0,0 +1,235 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_socket_set(3) +--- +<h1>nng_socket_set(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_socket_set - set socket option</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_set</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">valsz</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_set_bool</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">bval</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_set_int</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">ival</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_set_ms</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">dur</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_set_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">ptr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_set_size</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">z</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_set_string</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">str</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_socket_set_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">u64</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <code>nng_socket_set()</code> functions are used to configure options for +the socket <em>s</em>. +The actual options that may be configured in this way vary, and are +specified by <em>opt</em>. +A number of them are documented in <a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Protocol-specific options are documented with the protocol in question.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Access to transport options via this function is deprecated, and may be +removed from a future release. Applications should instead make use of +<a href="nng_dialer_set.3.html">nng_dialer_get</a> or +<a href="nng_listener_set.3.html">nng_listener_get</a> for specific dialers or listeners. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and is documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_socket_set()</code></dt> +<dd> +<p>This function is untyped, and can be used to configure any arbitrary data. +The <em>val</em> pointer addresses the data to copy, and <em>valsz</em> is the +size of the objected located at <em>val</em>.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_socket_set_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>). +The <em>bval</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_socket_set_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>). +The <em>ival</em> is passed to the option.</p> +</dd> +<dt class="hdlist1"><code>nng_socket_set_ms()</code></dt> +<dd> +<p>This function is used to configure time durations (such as timeouts) using +type <a href="nng_duration.5.html"><code>nng_duration</code></a>. +The duration <em>dur</em> is an integer number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_socket_set_ptr()</code></dt> +<dd> +<p>This function is used to pass a pointer, <em>ptr</em>, to structured data. +The data referenced by <em>ptr</em> is generally managed by other functions. +For example, TLS configuration objects created with +(<a href="nng_tls_config_alloc.3tls.html"><code>nng_tls_config_alloc()</code></a>) +can be passed this way.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_socket_set_size()</code></dt> +<dd> +<p>This function is used to configure a size, <em>z</em>, typically for buffer sizes, +message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_socket_set_string()</code></dt> +<dd> +<p>This function is used to pass configure a string, <em>str</em>. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a <code>NUL</code> (<code>\0</code>) byte. +(Other constraints may apply as well, see the documentation for each option +for details.)</p> +</dd> +<dt class="hdlist1"><code>nng_socket_set_uint64()</code></dt> +<dd> +<p>This function is used to configure a 64-bit unsigned value, <em>u64</em>. +This is typically used for options related to identifiers, network numbers, +and similar.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>Parameter <em>s</em> does not refer to an open socket.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The value being passed is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EREADONLY</code> +</td> +<td class="hdlist2"> +<p>The option <em>opt</em> is read-only.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The socket is in an inappropriate state for setting this option.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket_get.3.html">nng_socket_get(3)</a>, +<a href="nng_dialer_set.3.html">nng_dialer_set(3)</a>, +<a href="nng_listener_set.3.html">nng_listener_set(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat.5.html b/man/v1.7.2/nng_stat.5.html new file mode 100644 index 00000000..410704d8 --- /dev/null +++ b/man/v1.7.2/nng_stat.5.html @@ -0,0 +1,117 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat(5) +--- +<h1>nng_stat(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat - statistic</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>An <code>nng_stat</code> represents a statistic. +All statistics have names (<a href="nng_stat_name.3.html"><code>nng_stat_name()</code></a>) and +descriptions (<a href="nng_stat_desc.3.html"><code>nng_stat_desc()</code></a>), and are +typed (<a href="nng_stat_type.3.html"><code>nng_stat_type()</code></a>).</p> +</div> +<div class="paragraph"> +<p>Most statistics are numeric, +and thus carry a value (<a href="nng_stat_value.3.html"><code>nng_stat_value()</code></a>) +and frequently also a unit that the value measures (<a href="nng_stat_unit.3.html"><code>nng_stat_unit()</code></a>).</p> +</div> +<div class="paragraph"> +<p>Some statistics however, are simply strings (<a href="nng_stat_string.3.html"><code>nng_stat_string()</code></a>), +and thus carry no numeric value.</p> +</div> +<div class="paragraph"> +<p>Statistics are organized as a tree, and any given statistic can have siblings +(<a href="nng_stat_next.3.html"><code>nng_stat_next()</code></a>). +Note however that generally only <code>NNG_STAT_SCOPE</code> statistics, which are +act as placeholders in the tree (and carry no value), +will have children (<a href="nng_stat_child.3.html"><code>nng_stat_child()</code></a>).</p> +</div> +<div class="paragraph"> +<p>A tree of statistics is collected using <a href="nng_stats_get.3.html"><code>nng_stats_get()</code></a>, +and can be freed when no longer needed with <a href="nng_stats_free.3.html"><code>nng_stats_free()</code></a>. +This collection process is generally performed in a way to minimize impact +to running operations, but there is still some impact caused by collection +of statistics.</p> +</div> +<div class="paragraph"> +<p>The time when a statistic’s value is captured can be obtained using +<a href="nng_stat_timestamp.3.html"><code>nng_stat_timestamp()</code></a>, which is useful for +measuring rates of change in certain statistics.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The presence, names, and meanings of any given statistic are +subject to change at any time. These statistics are provided as an aid +for debugging, and should generally not be relied upon for programmatic +behaviors. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Statistics may be disabled by build-time configuration options, +in order to reduce program size and run-time overheads. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stats_free.3.html">nng_stats_free(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat_child.3.html">nng_stat_child(3)</a>, +<a href="nng_stat_desc.3.html">nng_stat_desc(3)</a>, +<a href="nng_stat_find.3.html">nng_stat_find(3)</a>, +<a href="nng_stat_find_dialer.3.html">nng_stat_find_dialer(3)</a>, +<a href="nng_stat_find_listener.3.html">nng_stat_find_listener(3)</a>, +<a href="nng_stat_find_socket.3.html">nng_stat_find_socket(3)</a>, +<a href="nng_stat_name.3.html">nng_stat_name(3)</a>, +<a href="nng_stat_next.3.html">nng_stat_next(3)</a>, +<a href="nng_stat_string.3.html">nng_stat_string(3)</a>, +<a href="nng_stat_timestamp.3.html">nng_stat_timestamp(3)</a>, +<a href="nng_stat_type.3.html">nng_stat_type(3)</a>, +<a href="nng_stat_unit.3.html">nng_stat_unit(3)</a>, +<a href="nng_stat_value.3.html">nng_stat_value(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_bool.3.html b/man/v1.7.2/nng_stat_bool.3.html new file mode 100644 index 00000000..a27fdb51 --- /dev/null +++ b/man/v1.7.2/nng_stat_bool.3.html @@ -0,0 +1,68 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_bool(3) +--- +<h1>nng_stat_bool(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_bool - get statistic Boolean value</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-nf">nng_stat_bool</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_bool()</code> function returns the Boolean value for the statistic <em>stat</em>. +Otherwise, if the statistic is not of Boolean type, the result is indeterminate. +See <a href="nng_stat_type.3.html"><code>nng_stat_type()</code></a> for a description of statistic types.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The boolean value associated with <em>stat</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat_type.3.html">nng_stat_type(3)</a>, +<a href="nng_stat_unit.3.html">nng_stat_unit(3)</a>, +<a href="nng_stat_value.3.html">nng_stat_value(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_child.3.html b/man/v1.7.2/nng_stat_child.3.html new file mode 100644 index 00000000..fbfbfe9d --- /dev/null +++ b/man/v1.7.2/nng_stat_child.3.html @@ -0,0 +1,79 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_child(3) +--- +<h1>nng_stat_child(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_child - get child statistic</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_stat_child</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">parent</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_child()</code> function returns the first child statistic of the +statistic <em>parent</em>. +If no children are present, then <code>NULL</code> is returned.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Only statistics with type (see <a href="nng_stat_type.3.html"><code>nng_stat_type()</code></a>) +of <code>NNG_STAT_SCOPE</code> will have children. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The first child statistic of <em>parent</em>, or NULL if <em>parent</em> has no children.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stat_next.3.html">nng_stat_next(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_desc.3.html b/man/v1.7.2/nng_stat_desc.3.html new file mode 100644 index 00000000..1a081dfa --- /dev/null +++ b/man/v1.7.2/nng_stat_desc.3.html @@ -0,0 +1,90 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_desc(3) +--- +<h1>nng_stat_desc(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_desc - get statistic description</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_stat_desc</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_desc()</code> function returns a brief, human-readable description +for the statistic <em>stat</em>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This description can be used for a tool-tip in user interfaces +displaying these statistic values. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +At this time, only English descriptions are provided. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The description of statistic <em>stat</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stat_name.3.html">nng_stats_name(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_find.3.html b/man/v1.7.2/nng_stat_find.3.html new file mode 100644 index 00000000..027b543d --- /dev/null +++ b/man/v1.7.2/nng_stat_find.3.html @@ -0,0 +1,81 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_find(3) +--- +<h1>nng_stat_find(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_find - find statistic by name</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_stat_find</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">name</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_find()</code> function searches the statistics tree <em>stat</em>, looking for a statistic whose name is <em>name</em>. +If it finds one, it returns it. +Otherwise <code>NULL</code> is returned.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +If multiple statistics have that name, then only the first match is returned. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The matching statistic, or NULL if no match is found.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stat_child.3.html">nng_stat_child(3)</a>, +<a href="nng_stat_find_dialer.3.html">nng_stat_find_dialer(3)</a>, +<a href="nng_stat_find_listener.3.html">nng_stat_find_listner(3)</a>, +<a href="nng_stat_find_socket.3.html">nng_stat_find_socket(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_find_dialer.3.html b/man/v1.7.2/nng_stat_find_dialer.3.html new file mode 100644 index 00000000..9bf9fa02 --- /dev/null +++ b/man/v1.7.2/nng_stat_find_dialer.3.html @@ -0,0 +1,76 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_find_dialer(3) +--- +<h1>nng_stat_find_dialer(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_find_dialer - find dialer statistics</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">nng_dialer</span><span class="tok-p">;</span> + +<span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_stat_find_dialer</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_dialer</span><span class="tok-w"> </span><span class="tok-n">dialer</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_find_dialer()</code> function returns the statistics tree within <em>stat</em> associated with the dialer <em>dialer</em>, if such a tree exists. +Otherwise <code>NULL</code> is returned.</p> +</div> +<div class="paragraph"> +<p>Generally, there will be child statistics of the returned value, each corresponding to a specific metric. +These can be further scanned using either +<a href="nng_stat_find.3.html">nng_stat_find(3)</a> +or by walking the tree with +<a href="nng_stat_child.3.html">nng_stat_child(3)</a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The matching statistic, or NULL if no match is found.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stat_child.3.html">nng_stat_child(3)</a>, +<a href="nng_stat_find.3.html">nng_stat_find(3)</a>, +<a href="nng_stat_find_listener.3.html">nng_stat_find_listener(3)</a>, +<a href="nng_stat_find_socket.3.html">nng_stat_find_socket(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_find_listener.3.html b/man/v1.7.2/nng_stat_find_listener.3.html new file mode 100644 index 00000000..e793c270 --- /dev/null +++ b/man/v1.7.2/nng_stat_find_listener.3.html @@ -0,0 +1,76 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_find_listener(3) +--- +<h1>nng_stat_find_listener(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_find_listener - find listener statistics</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_listener</span><span class="tok-w"> </span><span class="tok-n">nng_listener</span><span class="tok-p">;</span> + +<span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_stat_find_listener</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_listener</span><span class="tok-w"> </span><span class="tok-n">listener</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_find_listener()</code> function returns the statistics tree within <em>stat</em> associated with the listener <em>listener</em>, if such a tree exists. +Otherwise <code>NULL</code> is returned.</p> +</div> +<div class="paragraph"> +<p>Generally, there will be child statistics of the returned value, each corresponding to a specific metric. +These can be further scanned using either +<a href="nng_stat_find.3.html">nng_stat_find(3)</a> +or by walking the tree with +<a href="nng_stat_child.3.html">nng_stat_child(3)</a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The matching statistic, or NULL if no match is found.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stat_child.3.html">nng_stat_child(3)</a>, +<a href="nng_stat_find.3.html">nng_stat_find(3)</a>, +<a href="nng_stat_find_dialer.3.html">nng_stat_find_dialer(3)</a>, +<a href="nng_stat_find_socket.3.html">nng_stat_find_socket(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_find_socket.3.html b/man/v1.7.2/nng_stat_find_socket.3.html new file mode 100644 index 00000000..89b13529 --- /dev/null +++ b/man/v1.7.2/nng_stat_find_socket.3.html @@ -0,0 +1,76 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_find_socket(3) +--- +<h1>nng_stat_find_socket(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_find_socket - find socket statistics</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_socket</span><span class="tok-w"> </span><span class="tok-n">nng_socket</span><span class="tok-p">;</span> + +<span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_stat_find_socket</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-n">socket</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_find_socket()</code> function returns the statistics tree within <em>stat</em> associated with the socket <em>socket</em>, if such a tree exists. +Otherwise <code>NULL</code> is returned.</p> +</div> +<div class="paragraph"> +<p>Generally, there will be child statistics of the returned value, each corresponding to a specific metric. +These can be further scanned using either +<a href="nng_stat_find.3.html">nng_stat_find(3)</a> +or by walking the tree with +<a href="nng_stat_child.3.html">nng_stat_child(3)</a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The matching statistic, or NULL if no match is found.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stat_child.3.html">nng_stat_child(3)</a>, +<a href="nng_stat_find.3.html">nng_stat_find(3)</a>, +<a href="nng_stat_find_dialer.3.html">nng_stat_find_dialer(3)</a>, +<a href="nng_stat_find_listener.3.html">nng_stat_find_listener(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_name.3.html b/man/v1.7.2/nng_stat_name.3.html new file mode 100644 index 00000000..3b25c083 --- /dev/null +++ b/man/v1.7.2/nng_stat_name.3.html @@ -0,0 +1,75 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_name(3) +--- +<h1>nng_stat_name(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_name - get statistic name</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_stat_name</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_name()</code> function returns the name for the statistic <em>stat</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The global root statistic will have the empty string ("") as it’s name. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The name of statistic <em>stat</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_next.3.html b/man/v1.7.2/nng_stat_next.3.html new file mode 100644 index 00000000..4195fd84 --- /dev/null +++ b/man/v1.7.2/nng_stat_next.3.html @@ -0,0 +1,66 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_next(3) +--- +<h1>nng_stat_next(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_next - get next statistic</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_stat_next</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_next()</code> function returns the next sibling statistic of the +statistic <em>stat</em>. +If no more siblings are present, then <code>NULL</code> is returned.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The next sibling statistic of <em>stat</em>, or NULL if <em>stat</em> is the last sibling.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stat_child.3.html">nng_stat_child(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_string.3.html b/man/v1.7.2/nng_stat_string.3.html new file mode 100644 index 00000000..28431e83 --- /dev/null +++ b/man/v1.7.2/nng_stat_string.3.html @@ -0,0 +1,83 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_string(3) +--- +<h1>nng_stat_string(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_string - get statistic string value</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_stat_string</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_string()</code> function returns a string value for the statistic <em>stat</em>, +which must be of type <code>NNG_STAT_STRING</code> (see <a href="nng_stat_type.3.html"><code>nng_stat_type(3)</code></a>).</p> +</div> +<div class="paragraph"> +<p>If the statistic is not of type <code>NNG_STAT_STRING</code>, then <code>NULL</code> will be returned.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The returned string is valid until <a href="nng_stats_free.3.html"><code>nng_stats_free()</code></a> is called to +free the memory for the snapshot. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The string value associated with <em>stat</em>, or <code>NULL</code> if the statistic is not +a string type.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat_type.3.html">nng_stats_type(3)</a>, +<a href="nng_stat_value.3.html">nng_stats_value(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_timestamp.3.html b/man/v1.7.2/nng_stat_timestamp.3.html new file mode 100644 index 00000000..80710713 --- /dev/null +++ b/man/v1.7.2/nng_stat_timestamp.3.html @@ -0,0 +1,99 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_timestamp(3) +--- +<h1>nng_stat_timestamp(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_timestamp - get statistic timestamp</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-nf">nng_stat_timestamp</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_timestamp()</code> function returns the a timestamp, which is measured +as a number of milliseconds since some arbitrary value in the past.</p> +</div> +<div class="paragraph"> +<p>Even within the same snapshot, statistics might have different timestamp +values, as the timestamp represents the time when that particular statistic +was captured.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +These values are intended to facilitate calculation of rates, by +comparing values from one snapshot with a subsequent one. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The values used here have the same offset as the +<a href="nng_clock.3supp.html"><code>nng_clock()</code></a> supplemental function. +This can be useful when converting these values to local clock time. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The timestamp when <em>stat</em> was captured, measured as a number of +milliseconds since some time in the past.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat_value.3.html">nng_stat_value(3)</a>, +<a href="nng_clock.3supp.html">nng_clock(3supp)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_type.3.html b/man/v1.7.2/nng_stat_type.3.html new file mode 100644 index 00000000..27d4ab13 --- /dev/null +++ b/man/v1.7.2/nng_stat_type.3.html @@ -0,0 +1,134 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_type(3) +--- +<h1>nng_stat_type(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_type - get statistic type</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_STAT_SCOPE</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_STAT_LEVEL</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_STAT_COUNTER</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_STAT_STRING</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_STAT_BOOLEAN</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_STAT_ID</span> +<span class="tok-p">};</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stat_type</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_type()</code> function returns the type of the statistic <em>stat</em>.</p> +</div> +<div class="paragraph"> +<p>The returned type will be one of the following values:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_STAT_SCOPE</code></dt> +<dd> +<p>This is a placeholder providing scope, and carries no value on its own. +Instead it is a parent node with child statistics (see +<a href="nng_stat_child.3.html"><code>nng_stat_child()</code></a>.)</p> +</dd> +<dt class="hdlist1"><code>NNG_STAT_LEVEL</code></dt> +<dd> +<p>This is a numeric statistic, but its value is a level, so rate calculations +based on changes in this value should not be considered significant.</p> +</dd> +<dt class="hdlist1"><code>NNG_STAT_COUNTER</code></dt> +<dd> +<p>This is a numeric statistic that represents an increasing count, typically +of events, messages, or bytes. +Frequently, it is interesting to consider changes in this statistic divided +by time to obtain a rate. +(For example, throughput might be calculated as changes in a byte counter +divided by the interval over which the change occurred.)</p> +</dd> +<dt class="hdlist1"><code>NNG_STAT_STRING</code></dt> +<dd> +<p>This is a string, and carries no numeric value. +Instead the <a href="nng_stat_string.3.html"><code>nng_stat_string()</code></a> function +should be used to obtain the value.</p> +</dd> +<dt class="hdlist1"><code>NNG_STAT_BOOLEAN</code></dt> +<dd> +<p>This is a boolean value. +The <a href="nng_stat_value.3.html"><code>nng_stat_value()</code></a> function will return zero +to represent a <code>false</code> value, and one to represent a <code>true</code> value.</p> +</dd> +</dl> +</div> +<div class="paragraph"> +<p><code>NNG_STAT_ID</code>: +The statistic is a numeric ID. +These are generally immutable values that represent an identity that might +be used with another interface.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +For <code>NNG_STAT_COUNTER</code> and <code>NNG_STAT_LEVEL</code> statistics, the +<a href="nng_stat_unit.3.html"><code>nng_stat_unit()</code></a> function will provide more +detail about the units measured by the static. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The statistic type for <em>stat</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat_string.3.html">nng_stat_string(3)</a>, +<a href="nng_stat_unit.3.html">nng_stat_unit(3)</a>, +<a href="nng_stat_value.3.html">nng_stat_value(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_unit.3.html b/man/v1.7.2/nng_stat_unit.3.html new file mode 100644 index 00000000..2b1cb0a0 --- /dev/null +++ b/man/v1.7.2/nng_stat_unit.3.html @@ -0,0 +1,125 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_unit(3) +--- +<h1>nng_stat_unit(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_unit - get statistic unit</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_UNIT_NONE</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_UNIT_BYTES</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_UNIT_MESSAGES</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_UNIT_MILLIS</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_UNIT_EVENTS</span> +<span class="tok-p">};</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stat_unit</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_unit()</code> function returns the unit of quantity measured +by the statistic <em>stat</em>.</p> +</div> +<div class="paragraph"> +<p>The returned value will be one of the following values:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_UNIT_NONE</code></dt> +<dd> +<p>There are no particular units measured. +In some cases there may be units, but the type of the unit will be obvious +from the name (see <a href="nng_stat_name.3.html"><code>nng_stat_name()</code></a>) of the statistic.</p> +</dd> +<dt class="hdlist1"><code>NNG_UNIT_BYTES</code></dt> +<dd> +<p>The statistic is a count of bytes.</p> +</dd> +<dt class="hdlist1"><code>NNG_UNIT_MESSAGES</code></dt> +<dd> +<p>The statistic is a count of messages. +Typically, one message corresponds to a single <a href="nng_msg.5.html"><code>nng_msg</code></a> structure.</p> +</dd> +<dt class="hdlist1"><code>NNG_UNIT_MILLIS</code></dt> +<dd> +<p>The statistic is a count of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>NNG_STAT_EVENTS</code></dt> +<dd> +<p>The statistic is a count of some other type of event.</p> +</dd> +</dl> +</div> +<div class="paragraph"> +<p>For statistics that are neither <code>NNG_STAT_COUNTER</code> nor <code>NNG_STAT_LEVEL</code> +type (see <a href="nng_stat_type.3.html"><code>nng_stat_type()</code></a>), the unit will +generally be <code>NNG_UNIT_NONE</code>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Normally rates can be calculated for <code>NNG_STAT_COUNTER</code> values for +any of these units, but for <code>NNG_UNIT_MILLIS</code> rate calculations are generally +meaningless. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The units measured by <em>stat</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat_name.3.html">nng_stat_name(3)</a>, +<a href="nng_stat_type.3.html">nng_stat_type(3)</a>, +<a href="nng_stat_value.3.html">nng_stat_value(3)</a>, +<a href="nng_msg.5.html">nng_msg(5)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stat_value.3.html b/man/v1.7.2/nng_stat_value.3.html new file mode 100644 index 00000000..5ccbefb6 --- /dev/null +++ b/man/v1.7.2/nng_stat_value.3.html @@ -0,0 +1,68 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stat_value(3) +--- +<h1>nng_stat_value(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stat_value - get statistic numeric value</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-nf">nng_stat_value</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">stat</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_value()</code> function returns a numeric value for the statistic <em>stat</em>. +If the statistic is not of numeric type, then zero is returned. +See <a href="nng_stat_type.3.html"><code>nng_stat_type()</code></a> for a description of statistic types.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The numeric value associated with <em>stat</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat_bool.3.html">nng_stat_bool(3)</a>, +<a href="nng_stat_type.3.html">nng_stat_type(3)</a>, +<a href="nng_stat_unit.3.html">nng_stat_unit(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stats_free.3.html b/man/v1.7.2/nng_stats_free.3.html new file mode 100644 index 00000000..f5f4a7b4 --- /dev/null +++ b/man/v1.7.2/nng_stats_free.3.html @@ -0,0 +1,79 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stats_free(3) +--- +<h1>nng_stats_free(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stats_free - free statistics snapshot</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_stats_free</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stats_free()</code> function deallocates a statistics snapshot +previously collected with +<a href="nng_stats_get.3.html"><code>nng_stats_get()</code></a>. +After calling this, all values associated with the snapshot are +invalidated.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Only the top of the collected statistics tree can be +freed using this function. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_stats_get.3.html">nng_stats_get(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stats_get.3.html b/man/v1.7.2/nng_stats_get.3.html new file mode 100644 index 00000000..aa3990b6 --- /dev/null +++ b/man/v1.7.2/nng_stats_get.3.html @@ -0,0 +1,152 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stats_get(3) +--- +<h1>nng_stats_get(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stats_get - get statistics snapshot</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stat</span><span class="tok-w"> </span><span class="tok-n">nng_stat</span><span class="tok-p">;</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">nng_stats_get</span><span class="tok-p">(</span><span class="tok-n">nng_stat</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">statsp</span><span class="tok-p">)</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stat_get()</code> function attempts to obtain a snapshot of all the +various diagnostic statistics that are present in the system.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The process of collecting statistics is designed to have minimal +impact on the system, but there is still some impact. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The statistics are organized as a tree, rooted with a parent +statistic of type <code>NNG_STAT_SCOPE</code> that carries no value, and which +has an empty name. +This parent statistic is returned through the <em>statsp</em> pointer.</p> +</div> +<div class="paragraph"> +<p>The <a href="nng_stat_child.3.html"><code>nng_stat_child()</code></a> and +<a href="nng_stat_next.3.html"><code>nng_stat_next()</code></a> function can be used to +iterate over the the tree.</p> +</div> +<div class="paragraph"> +<p>When no longer needed, the statistics can be freed with the +<a href="nng_stats_free.3.html"><code>nng_stats_free()</code></a> function, but that +function must be called only with the root statistic that is returned +through the <em>statsp</em> pointer.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The values of individual statistics are guaranteed to be atomic, +but due the way statistics are collected there can be discrepancies between them at certain times. +For example, statistics counting bytes and messages received may not +reflect the same number of messages, depending on when the snapshot is taken. +This potential inconsistency arises as a result of optimizations to minimize +the impact of statistics on actual operations. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The names, values, and semantics of statistics provided may change +from release to release. +These are provided for informational and debugging use only, and applications +should not rely on the presence, names, or meanings of any individual statistics. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns a pointer to the allocated memory on success, +and <code>NULL</code> otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to collect statistics.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>Statistics are not supported (compile time option).</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_stats_free.3.html">nng_stats_free(3)</a>, +<a href="nng_stat_child.3.html">nng_stat_child(3)</a>, +<a href="nng_stat_desc.3.html">nng_stat_desc(3)</a>, +<a href="nng_stat_name.3.html">nng_stat_name(3)</a>, +<a href="nng_stat_next.3.html">nng_stat_next(3)</a>, +<a href="nng_stat_string.3.html">nng_stat_string(3)</a>, +<a href="nng_stat_type.3.html">nng_stat_type(3)</a>, +<a href="nng_stat_timestamp.3.html">nng_stat_timestamp(3)</a>, +<a href="nng_stat_unit.3.html">nng_stat_unit(3)</a>, +<a href="nng_stat_value.3.html">nng_stat_value(3)</a>, +<a href="nng_stat.5.html">nng_stat(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_strdup.3.html b/man/v1.7.2/nng_strdup.3.html new file mode 100644 index 00000000..1d09cd6d --- /dev/null +++ b/man/v1.7.2/nng_strdup.3.html @@ -0,0 +1,86 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_strdup(3) +--- +<h1>nng_strdup(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_strdup - duplicate string</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_strdup</span><span class="tok-p">(</span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">src</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_strdup()</code> duplicates the string <em>src</em> and returns it.</p> +</div> +<div class="paragraph"> +<p>This is logically equivalent to using <a href="nng_alloc.3.html"><code>nng_alloc()</code></a> +to allocate a region of memory of <code>strlen(s) + 1</code> bytes, and then +using <code>strcpy()</code> to copy the string into the destination before +returning it.</p> +</div> +<div class="paragraph"> +<p>The returned string should be deallocated with +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a>, or may be deallocated using the +<a href="nng_free.3.html"><code>nng_free()</code></a> using the length of the returned string plus +one (for the <code>NUL</code> terminating byte).</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Do not use the system <code>free()</code> or similar functions to deallocate +the string, since those may use a different memory arena! +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the new string on success, and <code>NULL</code> on failure.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>No errors are returned, but a <code>NULL</code> return value should be +treated the same as <code>NNG_ENOMEM</code>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_alloc.3.html">nng_alloc(3)</a>, +<a href="nng_free.3.html">nng_free(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream.5.html b/man/v1.7.2/nng_stream.5.html new file mode 100644 index 00000000..f6399b69 --- /dev/null +++ b/man/v1.7.2/nng_stream.5.html @@ -0,0 +1,114 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream(5) +--- +<h1>nng_stream(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream - byte stream</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stream</span><span class="tok-w"> </span><span class="tok-n">nng_stream</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>An <code>nng_stream</code> represents a byte stream. +This may correspond to an underlying connection such a TCP connection or +a connected UNIX domain socket or named pipe.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The <code>nng_stream</code> object is used for raw byte stream connections, and +should not be confused with a pipe object created on +<a href="nng_socket.5.html">socket</a> using the +<a href="nng_listen.3.html"><code>nng_listen()</code></a>, +<a href="nng_dial.3.html"><code>nng_dial()</code></a> or related functions. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>These objects are created either establishing an outgoing connection +with +<a href="nng_stream_dialer_dial.3str.html"><code>nng_stream_dialer_dial()</code></a> +or by accepting in incoming connection with +<a href="nng_stream_listener_accept.3str.html"><code>nng_stream_listener_accept()</code></a>.</p> +</div> +<div class="paragraph"> +<p>Byte streams are reliable in that data +will not be delivered out of order, or with portions missing.</p> +</div> +<div class="paragraph"> +<p>Data can be sent using +<a href="nng_stream_send.3str.html"><code>nng_stream_send()</code></a> or +received with +<a href="nng_stream_recv.3str.html"><code>nng_stream_recv()</code></a>.</p> +</div> +<div class="paragraph"> +<p>When the connection is no longer needed, it should be freed with +<a href="nng_stream_free.3str.html"><code>nng_stream_free()</code></a>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It is possible to close the connection, without freeing it, by +using +<a href="nng_stream_close.3str.html"><code>nng_stream_close()</code></a>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>Byte streams may, depending on the underlying technology, +support various +<a href="nng_options.5.html">options</a>, which +can be accessed using the +<a href="nng_stream_get.3str.html"><code>nng_stream_get()</code></a> and +<a href="nng_stream_set.3str.html"><code>nng_stream_set()</code></a> family of +functions.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng_stream_close.3str.html">nng_stream_close(3str)</a>, +<a href="nng_stream_dialer_dial.3str.html">nng_stream_dialer_dial(3str)</a>, +<a href="nng_stream_free.3str.html">nng_stream_free(3str)</a>, +<a href="nng_stream_get.3str.html">nng_stream_get(3str)</a>, +<a href="nng_stream_listener_accept.3str.html">nng_stream_listener_accept(3str)</a>, +<a href="nng_stream_recv.3str.html">nng_stream_recv(3str)</a>, +<a href="nng_stream_send.3str.html">nng_stream_send(3str)</a>, +<a href="nng_stream_set.3str.html">nng_stream_set(3str)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng.7.html">nng(7)</a>,</p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_close.3str.html b/man/v1.7.2/nng_stream_close.3str.html new file mode 100644 index 00000000..bf0b3f72 --- /dev/null +++ b/man/v1.7.2/nng_stream_close.3str.html @@ -0,0 +1,103 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_close(3str) +--- +<h1>nng_stream_close(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_close - close byte stream</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_close</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_close()</code> function closes the +<a href="nng_stream.5.html">byte stream</a> <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>If any operations are pending, such as +<a href="nng_stream_send.3str.html"><code>nng_stream_send()</code></a> +or +<a href="nng_stream_recv.3str.html"><code>nng_stream_recv()</code></a>, +they will be terminated with +an <code>NNG_ECLOSED</code> error condition. +Also, any new operations will fail with <code>NNG_ECLOSED</code> after the connection +is closed.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Closing the connection while data is in transmission will likely +lead to loss of that data. +There is no automatic linger or flush to ensure that the socket send buffers +have completely transmitted. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Closing the connection does not free the resources associated with it. +Once it is certain that no more operations are pending on the connection, +it should be freed with +<a href="nng_stream_free.3str.html"><code>nng_stream_free()</code></a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_free.3str.html">nng_stream_free(3str)</a>, +<a href="nng_stream_recv.3str.html">nng_stream_recv(3str)</a>, +<a href="nng_stream_send.3str.html">nng_stream_send(3str)</a>, +<a href="nng_stream.5.html">nng_stream(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_dialer.5.html b/man/v1.7.2/nng_stream_dialer.5.html new file mode 100644 index 00000000..eb4ae594 --- /dev/null +++ b/man/v1.7.2/nng_stream_dialer.5.html @@ -0,0 +1,65 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_dialer(5) +--- +<h1>nng_stream_dialer(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_dialer - byte stream dialer</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-n">nng_stream_dialer</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +An <code>nng_stream_dialer</code> is a handle to a dialer for byte streams, +and is responsible for creating +<a href="nng_stream.5.html"><code>nng_stream</code></a> objects (corresponding to connected byte +streams) by connecting to remote peers.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The <code>nng_stream_dialer</code> object is used for low-level byte stream +connections, and should not be confused with a high-level +<a href="nng_dialer.5.html"><code>nng_dialer</code></a> object. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_stream_dialer_alloc.3str.html">nng_stream_dialer_alloc(3str)</a>, +<a href="nng_stream_dialer_close.3str.html">nng_stream_dialer_close(3str)</a>, +<a href="nng_stream_dialer_dial.3str.html">nng_stream_dialer_dial(3str)</a>, +<a href="nng_stream_dialer_free.3str.html">nng_stream_dialer_free(3str)</a>, +<a href="nng_stream.5.html">nng_stream(5)</a>, +<a href="nng_stream_listener.5.html">nng_stream_listener(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_dialer_alloc.3str.html b/man/v1.7.2/nng_stream_dialer_alloc.3str.html new file mode 100644 index 00000000..712f9e64 --- /dev/null +++ b/man/v1.7.2/nng_stream_dialer_alloc.3str.html @@ -0,0 +1,111 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_dialer_alloc(3str) +--- +<h1>nng_stream_dialer_alloc(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_dialer_alloc - allocate byte stream dialer</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">dp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">addr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_alloc_url</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">dp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-n">nng_url</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions allocates a dialer for byte streams. +Dialers create +<a href="nng_stream.5.html"><code>nng_stream</code></a> objects by initiating outgoing +connections, via the +<a href="nng_stream_dialer_dial.3str.html"><code>nng_stream_dialer_dial()</code></a> function.</p> +</div> +<div class="paragraph"> +<p>The first form, <code>nng_stream_dialer_alloc()</code>, connects to the address +specified by <em>addr</em>, which should be a string representing a URL.</p> +</div> +<div class="paragraph"> +<p>The second form, <code>nng_stream_dialer_alloc_url()</code>, takes a pre-parsed +or pre-constructed +<a href="nng_url.5.html"><code>nng_url</code></a> object to determine the remote address.</p> +</div> +<div class="paragraph"> +<p>These functions may support different URL schemes, such as +<code>ipc://</code>, <code>tcp://</code>, <code>tls+tcp://</code>, or <code>ws://</code>.</p> +</div> +<div class="paragraph"> +<p>Both forms store the dialer in the location referenced by <em>dp</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The URL scheme is not supported by the implementation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINVAL</code> +</td> +<td class="hdlist2"> +<p>The URL requested is invalid.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_dialer_close.3str.html">nng_stream_dialer_close(3str)</a> +<a href="nng_stream_dialer_dial.3str.html">nng_stream_dialer_dial(3str)</a> +<a href="nng_stream_dialer_free.3str.html">nng_stream_dialer_free(3str)</a> +<a href="nng_stream_dialer_get.3str.html">nng_stream_dialer_get(3str)</a> +<a href="nng_stream_dialer_set.3str.html">nng_stream_dialer_set(3str)</a> +<a href="nng_stream_dialer.5.html">nng_stream_dialer(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_dialer_close.3str.html b/man/v1.7.2/nng_stream_dialer_close.3str.html new file mode 100644 index 00000000..17f3cc6e --- /dev/null +++ b/man/v1.7.2/nng_stream_dialer_close.3str.html @@ -0,0 +1,89 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_dialer_close(3str) +--- +<h1>nng_stream_dialer_close(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_dialer_close - close byte stream dialer</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_close</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_dialer_close()</code> function closes the supplied byte stream +dialer <em>d</em>, +but does not free the underlying resources associated with it.</p> +</div> +<div class="paragraph"> +<p>If any +<a href="nng_stream_dialer_dial.3str.html">dial</a> +operations using <em>d</em> are +in progress, they will be terminated with an <code>NNG_ECLOSED</code> error condition.</p> +</div> +<div class="paragraph"> +<p>Furthermore any future accesses to the dialer <em>d</em> will also result in +<code>NNG_ECLOSED</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function does not release the memory for the dialer, so the +application should still free the memory using +<a href="nng_stream_dialer_free.3str.html"><code>nng_stream_dialer_free()</code></a> +once it is certain that nothing else is using it. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_dialer_alloc.3str.html">nng_stream_dialer_alloc(3str)</a>, +<a href="nng_stream_dialer_dial.3str.html">nng_stream_dialer_dial(3str)</a>, +<a href="nng_stream_dialer_free.3str.html">nng_stream_dialer_free(3str)</a>, +<a href="nng_stream_dialer.5.html">nng_stream_dialer(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_dialer_dial.3str.html b/man/v1.7.2/nng_stream_dialer_dial.3str.html new file mode 100644 index 00000000..860ac3eb --- /dev/null +++ b/man/v1.7.2/nng_stream_dialer_dial.3str.html @@ -0,0 +1,136 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_dialer_dial(3str) +--- +<h1>nng_stream_dialer_dial(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_dialer_dial - initiate outgoing byte stream connection</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_dial</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_dialer_dial()</code> attempts to establish a connection to the +remote peer for the dialer <em>d</em>. +The operation is completed asynchronously, using <em>aio</em>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The peer address is determined by the address specified using +<a href="nng_stream_dialer_alloc.3str.html"><code>nng_stream_dialer_alloc()</code></a> or +<a href="nng_stream_dialer_alloc.3str.html"><code>nng_stream_dialer_alloc_url()</code></a>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>If a connection is successfully established, the <em>aio</em> will have the +resulting +<a href="nng_stream.5.html"><code>nng_stream</code></a> object stored as its first output. +(See +<a href="nng_aio_get_output.3.html"><code>nng_aio_get_output()</code></a>.)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINVAL</code> +</td> +<td class="hdlist2"> +<p>The address specified is invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was aborted.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The dialer is closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNREFUSED</code> +</td> +<td class="hdlist2"> +<p>The connection was refused by the server.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The connection was reset by the server.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_dialer_alloc.3str.html">nng_stream_dialer_alloc(3str)</a>, +<a href="nng_stream_dialer_close.3str.html">nng_stream_dialer_close(3str)</a>, +<a href="nng_stream_dialer_free.3str.html">nng_stream_dialer_free(3str)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng_stream.5.html">nng_stream(5)</a>, +<a href="nng_stream_dialer.5.html">nng_stream_dialer(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_dialer_free.3str.html b/man/v1.7.2/nng_stream_dialer_free.3str.html new file mode 100644 index 00000000..400ffe13 --- /dev/null +++ b/man/v1.7.2/nng_stream_dialer_free.3str.html @@ -0,0 +1,82 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_dialer_free(3str) +--- +<h1>nng_stream_dialer_free(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_dialer_free - free byte stream dialer</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_free</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_dialer_free()</code> function closes the supplied +byte stream dialer <em>d</em>, +and frees the underlying resources associated with it.</p> +</div> +<div class="paragraph"> +<p>If any +<a href="nng_stream_dialer_dial.3str.html">dial</a> operations using <em>d</em> are +in progress, they will be terminated with an <code>NNG_ECLOSED</code> error condition.</p> +</div> +<div class="admonitionblock warning"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-warning" title="Warning"></i> +</td> +<td class="content"> +It is important that the application ensure that no further accesses +are made to <em>d</em>, as the memory backing it will be reclaimed for other uses. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_dialer_alloc.3str.html">nng_stream_dialer_alloc(3str)</a>, +<a href="nng_stream_dialer_close.3str.html">nng_stream_dialer_close(3str)</a>, +<a href="nng_stream_dialer_dial.3str.html">nng_stream_dialer_dial(3str)</a>, +<a href="nng_stream_dialer.5.html">nng_stream_dialer(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_dialer_get.3str.html b/man/v1.7.2/nng_stream_dialer_get.3str.html new file mode 100644 index 00000000..0eb57a54 --- /dev/null +++ b/man/v1.7.2/nng_stream_dialer_get.3str.html @@ -0,0 +1,227 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_dialer_get(3str) +--- +<h1>nng_stream_dialer_get(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_dialer_get - get option from byte stream dialer</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_get</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sizep</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_get_bool</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_get_int</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_get_ms</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_get_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_get_size</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_get_addr</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_get_string</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_get_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_dialer_get()</code> functions are used to retrieve option values for the +<a href="nng_stream_dialer.5.html">byte stream dialer</a> <em>d</em>.</p> +</div> +<div class="paragraph"> +<p>The actual options that may be retrieved in this way vary. +A number of them are documented in +<a href="nng_options.5.html">nng_options(5)</a> and additional linked documents.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the connected +byte stream dialer <em>d</em>. +The forms vary based on the type of the option they take.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_stream_dialer_get()</code></dt> +<dd> +<p>This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in <em>val</em>, +and the size of the buffer shall be stored at the location referenced by +<em>sizep</em>.</p> +<div class="paragraph"> +<p>When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>sizep</em>. +If the caller’s buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in <em>sizep</em> does not exceed the original buffer size.</p> +</div> +<div class="paragraph"> +<p>It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>sizep</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_get_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>).</p> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_get_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>).</p> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_get_ms()</code></dt> +<dd> +<p>This function is used to retrieve time +<a href="nng_duration.5.html">durations</a> +(such as timeouts), stored as a number of milliseconds. +(The special value <code>NNG_DURATION_INFINITE</code> means an infinite amount of time, and +the special value <code>NNG_DURATION_DEFAULT</code> means a context-specific default.)</p> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_get_ptr()</code></dt> +<dd> +<p>This function is used to retrieve a pointer to structured data. +The data referenced is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Care must be taken to ensure that the application respects any +considerations about the lifetime of the underlying object. +See the documentation for the option for more specific guidance. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_get_size()</code></dt> +<dd> +<p>This function is used to retrieve a size, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_get_addr()</code></dt> +<dd> +<p>This function is used to retrieve a +<a href="nng_sockaddr.5.html">socket address</a>.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_get_string()</code></dt> +<dd> +<p>This function is used to retrieve a <code>NULL</code>-terminated string. +This string is created from the source using +<a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_get_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value. +This is typically used for identifiers, network +numbers, and similar options.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The dialer is closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>There was insufficient space to receive the object. +The amount of data actually needed is returned in <em>sizep</em>.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option may not read.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_dialer_set.3str.html">nng_stream_dialer_set(3str)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_stream_dialer.5.html">nng_stream_dialer(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_dialer_set.3str.html b/man/v1.7.2/nng_stream_dialer_set.3str.html new file mode 100644 index 00000000..bd8154e1 --- /dev/null +++ b/man/v1.7.2/nng_stream_dialer_set.3str.html @@ -0,0 +1,214 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_dialer_set(3str) +--- +<h1>nng_stream_dialer_set(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_dialer_set - set option on byte stream dialer</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_set</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">name</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">data</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_set_bool</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_set_int</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_set_ms</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_set_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_set_size</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_set_string</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_set_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_dialer_set_addr</span><span class="tok-p">(</span><span class="tok-n">nng_stream_dialer</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">d</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_dialer_set()</code> functions are used to configure options for the +<a href="nng_stream.5.html">byte stream dialer</a> <em>d</em>. +The actual options that may be configured in this way vary, and are +specified by <em>opt</em>. +A number of them are documented in +<a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally some transport-specific and protocol-specific options are +documented with the transports and protocols themselves.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_stream_dialer_set()</code></dt> +<dd> +<p>This function is untyped, and can be used to configure any arbitrary data. +The <em>val</em> pointer addresses the data to copy, and <em>size</em> is the +size of the objected located at <em>val</em>.</p> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_set_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>).</p> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_set_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>).</p> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_set_ms()</code></dt> +<dd> +<p>This function is used to configure time durations (such as timeouts) using +the type +<a href="nng_duration.5.html"><code>nng_duration</code></a>. +The duration is an integer number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_set_ptr()</code></dt> +<dd> +<p>This function is used to pass a pointer to structured data. +The data referenced by is generally managed by other functions. +For example, TLS configuration objects created with +<a href="nng_tls_config_alloc.3tls.html"><code>nng_tls_config_alloc()</code></a> +can be passed this way.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied. +Please see the documentation for the specific option for further details. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_set_size()</code></dt> +<dd> +<p>This function is used to configure a size, typically for buffer sizes, +message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_set_string()</code></dt> +<dd> +<p>This function is used to pass configure a string. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a <code>NUL</code> (<code>\0</code>) byte. +(Other constraints may apply as well, see the documentation for each option +for details.)</p> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_set_uint64()</code></dt> +<dd> +<p>This function is used to configure a 64-bit unsigned value/ +This is typically used for identifiers, network numbers, +and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_dialer_set_addr()</code></dt> +<dd> +<p>This function is used to configure a +<a href="nng_sockaddr.5.html">socket address</a>. +The value is copied, and thus the caller may discard the supplied +value immediately after this function returns.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The dialer is closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Either <em>data</em> or <em>size</em> are invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EREADONLY</code> +</td> +<td class="hdlist2"> +<p>The option may not be modified.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_dialer_get.3str.html">nng_stream_dialer_get(3str)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_ipc_options.5.html">nng_ipc_options(5)</a>, +<a href="nng_tcp_options.5.html">nng_tcp_options(5)</a>, +<a href="nng_tls_options.5.html">nng_tls_options(5)</a>, +<a href="nng_stream_dialer.5.html">nng_stream_dialer(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_free.3str.html b/man/v1.7.2/nng_stream_free.3str.html new file mode 100644 index 00000000..4f319e16 --- /dev/null +++ b/man/v1.7.2/nng_stream_free.3str.html @@ -0,0 +1,99 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_free(3str) +--- +<h1>nng_stream_free(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_free - free byte stream</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_free</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_free()</code> function closes the +<a href="nng_stream.5.html">byte stream</a> <em>s</em>, +and frees the underlying resources associated with it.</p> +</div> +<div class="paragraph"> +<p>If any operations are pending, such as +<a href="nng_stream_send.3str.html"><code>nng_stream_send()</code></a> +or +<a href="nng_stream_recv.3str.html"><code>nng_stream_recv()</code></a>, +they will be terminated with an <code>NNG_ECLOSED</code> error condition.</p> +</div> +<div class="admonitionblock warning"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-warning" title="Warning"></i> +</td> +<td class="content"> +It is important that the application ensure that no further accesses +are made to <em>s</em>, as the memory backing it will be reclaimed for other uses. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Closing the connection while data is in transmission will likely +lead to loss of that data. +There is no automatic linger or flush to ensure that the socket send buffers +have completely transmitted. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_close.3str.html">nng_stream_close(3str)</a>, +<a href="nng_stream_recv.3str.html">nng_stream_recv(3str)</a>, +<a href="nng_stream_send.3str.html">nng_stream_send(3str)</a>, +<a href="nng_stream.5.html">nng_stream(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_get.3str.html b/man/v1.7.2/nng_stream_get.3str.html new file mode 100644 index 00000000..5c4912c3 --- /dev/null +++ b/man/v1.7.2/nng_stream_get.3str.html @@ -0,0 +1,230 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_get(3str) +--- +<h1>nng_stream_get(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_get - get option from byte stream</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_get</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sizep</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_get_bool</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_get_int</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_get_ms</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_get_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_get_size</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_get_addr</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_get_string</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_get_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_get()</code> functions are used to retrieve option values for the +<a href="nng_stream.5.html">byte stream</a> <em>conn</em>.</p> +</div> +<div class="paragraph"> +<p>The actual options that may be retrieved in this way vary. +A number of them are documented in +<a href="nng_options.5.html">nng_options(5)</a> and additional linked documents.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the connected +byte stream <em>s</em>. +The forms vary based on the type of the option they take.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_stream_get()</code></dt> +<dd> +<p>This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in <em>val</em>, +and the size of the buffer shall be stored at the location referenced by +<em>sizep</em>.</p> +<div class="paragraph"> +<p>When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>sizep</em>. +If the caller’s buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in <em>sizep</em> does not exceed the original buffer size.</p> +</div> +<div class="paragraph"> +<p>It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>sizep</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_stream_get_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>).</p> +</dd> +<dt class="hdlist1"><code>nng_stream_get_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>).</p> +</dd> +<dt class="hdlist1"><code>nng_stream_get_ms()</code></dt> +<dd> +<p>This function is used to retrieve time +<a href="nng_duration.5.html">durations</a> +(such as timeouts), stored as a number of milliseconds. +(The special value <code>NNG_DURATION_INFINITE</code> means an infinite amount of time, and +the special value <code>NNG_DURATION_DEFAULT</code> means a context-specific default.)</p> +</dd> +<dt class="hdlist1"><code>nng_stream_get_ptr()</code></dt> +<dd> +<p>This function is used to retrieve a pointer to structured data. +The data referenced is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Care must be taken to ensure that the application respects any +considerations about the lifetime of the underyling object. +See the documentation for the option for more specific guidance. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_stream_get_size()</code></dt> +<dd> +<p>This function is used to retrieve a size, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_get_addr()</code></dt> +<dd> +<p>This function is used to retrieve a +<a href="nng_sockaddr.5.html">socket address</a>.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_get_string()</code></dt> +<dd> +<p>This function is used to retrieve a <code>NULL</code>-terminated string. +This string is created from the source using +<a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_get_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value. +This is typically used for identifiers, network +numbers, and similar options.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection is closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>There was insufficient space to receive the object. +The amount of data actually needed is returned in <em>sizep</em>.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option may not read.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_set.3str.html">nng_stream_set(3str)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_ipc_options.5.html">nng_ipc_options(5)</a>, +<a href="nng_tcp_options.5.html">nng_tcp_options(5)</a>, +<a href="nng_tls_options.5.html">nng_tls_options(5)</a>, +<a href="nng_stream.5.html">nng_stream(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_listener.5.html b/man/v1.7.2/nng_stream_listener.5.html new file mode 100644 index 00000000..f63eece8 --- /dev/null +++ b/man/v1.7.2/nng_stream_listener.5.html @@ -0,0 +1,67 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_listener(5) +--- +<h1>nng_stream_listener(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_listener - byte stream listener</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-n">nng_stream_listener</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +An <code>nng_stream_listener</code> is a handle to a byte stream listener, +which is responsible for accepting incoming connections and creating +corresponding +<a href="nng_stream.5.html"><code>nng_stream</code></a> from them.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The <code>nng_stream_listener</code> object is a low-level object for +raw byte stream connections, +and should not be confused with a high-level +<a href="nng_listener.5.html"><code>nng_listener</code></a> object. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_stream_listener_accept.3str.html">nng_stream_listener_accept(3str)</a>, +<a href="nng_stream_listener_alloc.3str.html">nng_stream_listener_alloc(3str)</a>, +<a href="nng_stream_listener_close.3str.html">nng_stream_listener_close(3str)</a>, +<a href="nng_stream_listener_free.3str.html">nng_stream_listener_free(3str)</a>, +<a href="nng_stream_listener_listen.3str.html">nng_stream_listener_listen(3str)</a>, +<a href="nng_stream.5.html">nng_stream(5)</a>, +<a href="nng_stream_dialer.5.html">nng_stream_dialer(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_listener_accept.3str.html b/man/v1.7.2/nng_stream_listener_accept.3str.html new file mode 100644 index 00000000..9a4e8f62 --- /dev/null +++ b/man/v1.7.2/nng_stream_listener_accept.3str.html @@ -0,0 +1,119 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_listener_accept(3str) +--- +<h1>nng_stream_listener_accept(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_listener_accept - accept incoming byte stream connection</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_accept</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_listener_accept()</code> attempts to accept an incoming byte stream +connection from a remote peer, using the listener <em>l</em>. +The operation is completed asynchronously, using <em>aio</em>.</p> +</div> +<div class="paragraph"> +<p>This operation can only be done after the listener is already +<a href="nng_stream_listener_listen.3str.html">listening</a>.</p> +</div> +<div class="paragraph"> +<p>If a connection is successfully established, the <em>aio</em> will have the +resulting +<a href="nng_stream.5.html"><code>nng_stream</code></a> object stored as its first output, +which can be retrieved with +<a href="nng_aio_get_output.3.html"><code>nng_aio_get_output()</code></a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was aborted.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The listener is closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The connection was reset by the peer.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The listener is not not listening.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_listener_alloc.3str.html">nng_stream_listener_alloc(3str)</a>, +<a href="nng_stream_listener_close.3str.html">nng_stream_listener_close(3str)</a>, +<a href="nng_stream_listener_free.3str.html">nng_stream_listener_free(3str)</a>, +<a href="nng_stream_listener_listen.3str.html">nng_stream_listener_listen(3str)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng_stream.5.html">nng_stream(5)</a>, +<a href="nng_stream_listener.5.html">nng_stream_listener(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_listener_alloc.3str.html b/man/v1.7.2/nng_stream_listener_alloc.3str.html new file mode 100644 index 00000000..3ccc732d --- /dev/null +++ b/man/v1.7.2/nng_stream_listener_alloc.3str.html @@ -0,0 +1,113 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_listener_alloc(3str) +--- +<h1>nng_stream_listener_alloc(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_listener_alloc - allocate byte stream listener</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">lp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">addr</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_alloc_url</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">lp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-n">nng_url</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions allocates a listener for byte streams. +Listeners create +<a href="nng_stream.5.html"><code>nng_stream</code></a> objects by accepting incoming +connections, via the +<a href="nng_stream_listener_accept.3str.html"><code>nng_stream_listener_accept()</code></a> +function.</p> +</div> +<div class="paragraph"> +<p>The first form, <code>nng_stream_listener_alloc()</code>, connects to the address +specified by <em>addr</em>, which should be a string representing a URL.</p> +</div> +<div class="paragraph"> +<p>The second form, <code>nng_stream_listener_alloc_url()</code>, takes a pre-parsed +or pre-constructed +<a href="nng_url.5.html"><code>nng_url</code></a> object to determine the remote address.</p> +</div> +<div class="paragraph"> +<p>These functions may support different URL schemes, such as +<code>ipc://</code>, <code>tcp://</code>, <code>tls+tcp://</code>, or <code>ws://</code>.</p> +</div> +<div class="paragraph"> +<p>Both forms store the listener in the location referenced by <em>lp</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The URL scheme is not supported by the implementation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINVAL</code> +</td> +<td class="hdlist2"> +<p>The URL requested is invalid.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_listener_accept.3str.html">nng_stream_listener_accept(3str)</a> +<a href="nng_stream_listener_close.3str.html">nng_stream_listener_close(3str)</a> +<a href="nng_stream_listener_free.3str.html">nng_stream_listener_free(3str)</a> +<a href="nng_stream_listener_get.3str.html">nng_stream_listener_get(3str)</a> +<a href="nng_stream_listener_listen.3str.html">nng_stream_listener_listen(3str)</a> +<a href="nng_stream_listener_set.3str.html">nng_stream_listener_set(3str)</a> +<a href="nng_stream_listener.5.html">nng_stream_listener(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_listener_close.3str.html b/man/v1.7.2/nng_stream_listener_close.3str.html new file mode 100644 index 00000000..966f05b8 --- /dev/null +++ b/man/v1.7.2/nng_stream_listener_close.3str.html @@ -0,0 +1,89 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_listener_close(3str) +--- +<h1>nng_stream_listener_close(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_listener_close - close byte stream listener</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_close</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_listener_close()</code> function closes the supplied connected byte +stream listener <em>l</em>, +but does not free the underlying resources associated with it.</p> +</div> +<div class="paragraph"> +<p>If any +<a href="nng_stream_listener_accept.3str.html">accept</a> +operations using <em>d</em> are +in progress, they will be terminated with an <code>NNG_ECLOSED</code> error condition.</p> +</div> +<div class="paragraph"> +<p>Furthermore any future accesses to the listener <em>l</em> will also result in +<code>NNG_ECLOSED</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function does not release the memory for the listener, so the +application should still free the memory using +<a href="nng_stream_listener_free.3str.html"><code>nng_stream_listener_free()</code></a> +once it is certain that nothing else is using it. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_listener_accept.3str.html">nng_stream_listener_accept(3str)</a>, +<a href="nng_stream_listener_alloc.3str.html">nng_stream_listener_alloc(3str)</a>, +<a href="nng_stream_listener_free.3str.html">nng_stream_listener_free(3str)</a>, +<a href="nng_stream_listener.5.html">nng_stream_listener(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_listener_free.3str.html b/man/v1.7.2/nng_stream_listener_free.3str.html new file mode 100644 index 00000000..d520a784 --- /dev/null +++ b/man/v1.7.2/nng_stream_listener_free.3str.html @@ -0,0 +1,82 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_listener_free(3str) +--- +<h1>nng_stream_listener_free(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_listener_free - free byte stream listener</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_free</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-p">)</span><span class="tok-n">l</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_listener_free()</code> function closes the supplied +byte stream listener <em>l</em>, +and frees the underlying resources associated with it.</p> +</div> +<div class="paragraph"> +<p>If any +<a href="nng_stream_listener_accept.3str.html">accept</a> operations using __l are +in progress, they will be terminated with an <code>NNG_ECLOSED</code> error condition.</p> +</div> +<div class="admonitionblock warning"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-warning" title="Warning"></i> +</td> +<td class="content"> +It is important that the application ensure that no further accesses +are made to <em>l</em>, as the memory backing it will be reclaimed for other uses. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_listener_accept.3str.html">nng_stream_listener_accept(3str)</a>, +<a href="nng_stream_listener_alloc.3str.html">nng_stream_listener_alloc(3str)</a>, +<a href="nng_stream_listener_close.3str.html">nng_stream_listener_close(3str)</a>, +<a href="nng_stream_listener.5.html">nng_stream_listener(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_listener_get.3str.html b/man/v1.7.2/nng_stream_listener_get.3str.html new file mode 100644 index 00000000..6a5e35a1 --- /dev/null +++ b/man/v1.7.2/nng_stream_listener_get.3str.html @@ -0,0 +1,228 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_listener_get(3str) +--- +<h1>nng_stream_listener_get(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_listener_get - get option from byte stream listener</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_get</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">sizep</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_get_bool</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_get_int</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_get_ms</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_get_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_get_size</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_get_addr</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_get_string</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">valp</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_get_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">valp</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_listener_get()</code> functions are used to retrieve option values +for the +<a href="nng_stream_listener.5.html">byte stream listener</a> <em>l</em>.</p> +</div> +<div class="paragraph"> +<p>The actual options that may be retrieved in this way vary. +A number of them are documented in +<a href="nng_options.5.html">nng_options(5)</a> and additional linked documents.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>In all of these forms, the option <em>opt</em> is retrieved from the connected +byte stream listener <em>l</em>. +The forms vary based on the type of the option they take.</p> +</div> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_stream_listener_get()</code></dt> +<dd> +<p>This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in <em>val</em>, +and the size of the buffer shall be stored at the location referenced by +<em>sizep</em>.</p> +<div class="paragraph"> +<p>When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by <em>sizep</em>. +If the caller’s buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in <em>sizep</em> does not exceed the original buffer size.</p> +</div> +<div class="paragraph"> +<p>It is acceptable to pass <code>NULL</code> for <em>val</em> if the value in <em>sizep</em> is zero. +This can be used to determine the size of the buffer needed to receive +the object.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_get_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>).</p> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_get_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>).</p> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_get_ms()</code></dt> +<dd> +<p>This function is used to retrieve time +<a href="nng_duration.5.html">durations</a> +(such as timeouts), stored as a number of milliseconds. +(The special value <code>NNG_DURATION_INFINITE</code> means an infinite amount of time, and +the special value <code>NNG_DURATION_DEFAULT</code> means a context-specific default.)</p> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_get_ptr()</code></dt> +<dd> +<p>This function is used to retrieve a pointer to structured data. +The data referenced is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Care must be taken to ensure that the application respects any +considerations about the lifetime of the underyling object. +See the documentation for the option for more specific guidance. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_get_size()</code></dt> +<dd> +<p>This function is used to retrieve a size, +typically for buffer sizes, message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_get_addr()</code></dt> +<dd> +<p>This function is used to retrieve a +<a href="nng_sockaddr.5.html">socket address</a>.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_get_string()</code></dt> +<dd> +<p>This function is used to retrieve a <code>NULL</code>-terminated string. +This string is created from the source using +<a href="nng_strdup.3.html"><code>nng_strdup()</code></a> +and consequently must be freed by the caller using +<a href="nng_strfree.3.html"><code>nng_strfree()</code></a> when it is no longer needed.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_get_uint64()</code></dt> +<dd> +<p>This function is used to retrieve a 64-bit unsigned value. +This is typically used for identifiers, network +numbers, and similar options.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The listener is closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>There was insufficient space to receive the object. +The amount of data actually needed is returned in <em>sizep</em>.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EWRITEONLY</code> +</td> +<td class="hdlist2"> +<p>The option may not read.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_listener_set.3str.html">nng_stream_listener_set(3str)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_stream_listener.5.html">nng_stream_listener(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_listener_listen.3str.html b/man/v1.7.2/nng_stream_listener_listen.3str.html new file mode 100644 index 00000000..134148e7 --- /dev/null +++ b/man/v1.7.2/nng_stream_listener_listen.3str.html @@ -0,0 +1,115 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_listener_listen(3str) +--- +<h1>nng_stream_listener_listen(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_listener_listen - bind listener to configured address</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_listen</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_listener_listen()</code> attempts to bind the listener <em>l</em> +to the local address specified when the listener was created.</p> +</div> +<div class="paragraph"> +<p>This must generally be done before accepting incoming connections using +<a href="nng_stream_listener_accept.3str.html"><code>nng_stream_listener_accept()</code></a>.</p> +</div> +<div class="paragraph"> +<p>For some transports this will also perform other actiosn. For example, +with TCP listeners it will configure the +underlying port into passive mode, ready to +accept an incoming connection, and established a listen queue +for receiving incoming connections.</p> +</div> +<div class="paragraph"> +<p>If binding the listener requires allocation of an address (for example +when a TCP port number of zero is specified, indicating that an +ephemeral port should be used), this operation will allocate that +resource. +This can permit retrieval of the selected address using +<a href="nng_stream_listener_get.3str.html"><code>nng_stream_listener_get()</code></a>, +typically with the +<a href="nng_options.5.html#NNG_OPT_LOCADDR"><code>NNG_OPT_LOCADDR</code></a> option.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINUSE</code> +</td> +<td class="hdlist2"> +<p>The address is already in use.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EADDRINVAL</code> +</td> +<td class="hdlist2"> +<p>The address is invalid or unavailable.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The listener has been closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ESTATE</code> +</td> +<td class="hdlist2"> +<p>The listener is already bound.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_stream_listener_accept.3str.html">nng_stream_listener_accept(3str)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_listener.5.html">nng_stream_listener(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_listener_set.3str.html b/man/v1.7.2/nng_stream_listener_set.3str.html new file mode 100644 index 00000000..b58992e0 --- /dev/null +++ b/man/v1.7.2/nng_stream_listener_set.3str.html @@ -0,0 +1,214 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_listener_set(3str) +--- +<h1>nng_stream_listener_set(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_listener_set - set option on byte stream listener</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_set</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">name</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">data</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_set_bool</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_set_int</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_set_ms</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_set_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_set_size</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_set_string</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_set_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_listener_set_addr</span><span class="tok-p">(</span><span class="tok-n">nng_stream_listener</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">l</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_listener_set()</code> functions are used to configure options for the +<a href="nng_stream.5.html">byte stream listener</a> <em>l</em>. +The actual options that may be configured in this way vary, and are +specified by <em>opt</em>. +A number of them are documented in +<a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally some transport-specific and protocol-specific options are +documented with the transports and protocols themselves.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_stream_listener_set()</code></dt> +<dd> +<p>This function is untyped, and can be used to configure any arbitrary data. +The <em>val</em> pointer addresses the data to copy, and <em>size</em> is the +size of the objected located at <em>val</em>.</p> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_set_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>).</p> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_set_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>).</p> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_set_ms()</code></dt> +<dd> +<p>This function is used to configure time durations (such as timeouts) using +the type +<a href="nng_duration.5.html"><code>nng_duration</code></a>. +The duration is an integer number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_set_ptr()</code></dt> +<dd> +<p>This function is used to pass a pointer to structured data. +The data referenced by is generally managed by other functions. +For example, TLS configuration objects created with +<a href="nng_tls_config_alloc.3tls.html"><code>nng_tls_config_alloc()</code></a> +can be passed this way.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied. +Please see the documentation for the specific option for further details. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_set_size()</code></dt> +<dd> +<p>This function is used to configure a size, typically for buffer sizes, +message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_set_string()</code></dt> +<dd> +<p>This function is used to pass configure a string. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a <code>NUL</code> (<code>\0</code>) byte. +(Other constraints may apply as well, see the documentation for each option +for details.)</p> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_set_uint64()</code></dt> +<dd> +<p>This function is used to configure a 64-bit unsigned value/ +This is typically used for identifiers, network numbers, +and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_listener_set_addr()</code></dt> +<dd> +<p>This function is used to configure a +<a href="nng_sockaddr.5.html">socket address</a>. +The value is copied, and thus the caller may discard the supplied +value immediately after this function returns.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The listener is closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Either <em>data</em> or <em>size</em> are invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EREADONLY</code> +</td> +<td class="hdlist2"> +<p>The option may not be modified.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_listener_get.3str.html">nng_stream_listener_get(3str)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_ipc_options.5.html">nng_ipc_options(5)</a>, +<a href="nng_tcp_options.5.html">nng_tcp_options(5)</a>, +<a href="nng_tls_options.5.html">nng_tls_options(5)</a>, +<a href="nng_stream_listener.5.html">nng_stream_listener(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_recv.3str.html b/man/v1.7.2/nng_stream_recv.3str.html new file mode 100644 index 00000000..a116c6c0 --- /dev/null +++ b/man/v1.7.2/nng_stream_recv.3str.html @@ -0,0 +1,153 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_recv(3str) +--- +<h1>nng_stream_recv(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_recv - receive from byte stream</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_recv</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_recv()</code> function starts an asynchronous receive from the +<a href="nng_stream.5.html">byte stream</a> <em>s</em> +into the scatter/gather vector located in the +asynchronous I/O structure <em>aio</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The +<a href="nng_aio_set_iov.3.html"><code>nng_aio_set_iov()</code></a> function must have been +called first, to set the scatter/gather vector for <em>aio</em>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>This function returns immediately, with no return value. +Completion of the operation is signaled via the <em>aio</em>, +and the final result may be obtained via +<a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>. +That result will either be zero or an error code.</p> +</div> +<div class="paragraph"> +<p>The I/O operation completes as soon as at least one byte has been +received, or an error has occurred. +Therefore, the number of bytes read may be less than requested. +The actual number of bytes read can be determined with +<a href="nng_aio_count.3.html"><code>nng_aio_count()</code></a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The peer closed the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNSHUT</code> +</td> +<td class="hdlist2"> +<p>Remote peer shutdown after sending data.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The <em>aio</em> does not contain a valid scatter/gather vector.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Timeout waiting for data from the connection.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_count.3.html">nng_aio_count(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio_set_iov.3.html">nng_aio_set_iov(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_close.3str.html">nng_stream_close(3str)</a>, +<a href="nng_stream_send.3str.html">nng_stream_send(3str)</a>, +<a href="nng_stream.5.html">nng_stream(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_send.3str.html b/man/v1.7.2/nng_stream_send.3str.html new file mode 100644 index 00000000..6cde0524 --- /dev/null +++ b/man/v1.7.2/nng_stream_send.3str.html @@ -0,0 +1,146 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_send(3str) +--- +<h1>nng_stream_send(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_send - send to byte stream</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_send</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_aio</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">aio</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_send()</code> function starts an asynchronous send over the +<a href="nng_stream.5.html">byte stream</a> <em>s</em> +from the scatter/gather vector located in the +asynchronous I/O structure <em>aio</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The +<a href="nng_aio_set_iov.3.html"><code>nng_aio_set_iov()</code></a> +function must have been +called first, to set the scatter/gather vector for <em>aio</em>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>This function returns immediately, with no return value. +Completion of the operation is signaled via the <em>aio</em>, and the final +result may be obtained via +<a href="nng_aio_result.3.html"><code>nng_aio_result()</code></a>. +That result will either be zero or an error code.</p> +</div> +<div class="paragraph"> +<p>The I/O operation completes as soon as at least one byte has been +sent, or an error has occurred. +Therefore, the number of bytes sent may be less than requested. +The actual number of bytes sent can be determined with +<a href="nng_aio_count.3.html"><code>nng_aio_count()</code></a>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECANCELED</code> +</td> +<td class="hdlist2"> +<p>The operation was canceled.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection was closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ECONNRESET</code> +</td> +<td class="hdlist2"> +<p>The peer closed the connection.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The <em>aio</em> does not contain a valid scatter/gather vector.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory to perform the operation.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ETIMEDOUT</code> +</td> +<td class="hdlist2"> +<p>Timeout waiting for data from the connection.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_aio_alloc.3.html">nng_aio_alloc(3)</a>, +<a href="nng_aio_count.3.html">nng_aio_count(3)</a>, +<a href="nng_aio_result.3.html">nng_aio_result(3)</a>, +<a href="nng_aio_set_iov.3.html">nng_aio_set_iov(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_close.3str.html">nng_stream_close(3str)</a>, +<a href="nng_stream_recv.3str.html">nng_stream_recv(3str)</a>, +<a href="nng_stream.5.html">nng_stream(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_stream_set.3str.html b/man/v1.7.2/nng_stream_set.3str.html new file mode 100644 index 00000000..30699c8c --- /dev/null +++ b/man/v1.7.2/nng_stream_set.3str.html @@ -0,0 +1,214 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_stream_set(3str) +--- +<h1>nng_stream_set(3str)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_stream_set - set option on byte stream</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_set</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">name</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">data</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">size</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_set_bool</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_set_int</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_set_ms</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_duration</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_set_ptr</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_set_size</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">size_t</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_set_string</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_set_uint64</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">uint64_t</span><span class="tok-w"> </span><span class="tok-n">val</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_stream_set_addr</span><span class="tok-p">(</span><span class="tok-n">nng_stream</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">opt</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-n">nng_sockaddr</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">val</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_stream_set()</code> functions are used to configure options for the +<a href="nng_stream.5.html">byte stream</a> <em>s</em>. +The actual options that may be configured in this way vary, and are +specified by <em>opt</em>. +A number of them are documented in +<a href="nng_options.5.html">nng_options(5)</a>.</p> +</div> +<div class="paragraph"> +<p>Additionally some transport-specific and protocol-specific options are +documented with the transports and protocols themselves.</p> +</div> +<div class="sect2"> +<h3 id="_forms">Forms</h3> +<div class="paragraph"> +<p>The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>nng_stream_set()</code></dt> +<dd> +<p>This function is untyped, and can be used to configure any arbitrary data. +The <em>val</em> pointer addresses the data to copy, and <em>size</em> is the +size of the objected located at <em>val</em>.</p> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +It may be easier to use one of the typed forms of this function. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_stream_set_bool()</code></dt> +<dd> +<p>This function is for options which take a Boolean (<code>bool</code>).</p> +</dd> +<dt class="hdlist1"><code>nng_stream_set_int()</code></dt> +<dd> +<p>This function is for options which take an integer (<code>int</code>).</p> +</dd> +<dt class="hdlist1"><code>nng_stream_set_ms()</code></dt> +<dd> +<p>This function is used to configure time durations (such as timeouts) using +the type +<a href="nng_duration.5.html"><code>nng_duration</code></a>. +The duration is an integer number of milliseconds.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_set_ptr()</code></dt> +<dd> +<p>This function is used to pass a pointer to structured data. +The data referenced by is generally managed by other functions. +For example, TLS configuration objects created with +<a href="nng_tls_config_alloc.3tls.html"><code>nng_tls_config_alloc()</code></a> +can be passed this way.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This form is somewhat special in that the object is generally +not copied, but instead the <strong>pointer</strong> to the object is copied. +Please see the documentation for the specific option for further details. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>nng_stream_set_size()</code></dt> +<dd> +<p>This function is used to configure a size, typically for buffer sizes, +message maximum sizes, and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_set_string()</code></dt> +<dd> +<p>This function is used to pass configure a string. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a <code>NUL</code> (<code>\0</code>) byte. +(Other constraints may apply as well, see the documentation for each option +for details.)</p> +</dd> +<dt class="hdlist1"><code>nng_stream_set_uint64()</code></dt> +<dd> +<p>This function is used to configure a 64-bit unsigned value/ +This is typically used for identifiers, network numbers, +and similar options.</p> +</dd> +<dt class="hdlist1"><code>nng_stream_set_addr()</code></dt> +<dd> +<p>This function is used to configure a +<a href="nng_sockaddr.5.html">socket address</a>. +The value is copied, and thus the caller may discard the supplied +value immediately after this function returns.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ECLOSED</code> +</td> +<td class="hdlist2"> +<p>The connection is closed.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>Either <em>data</em> or <em>size</em> are invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The option is not supported.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EREADONLY</code> +</td> +<td class="hdlist2"> +<p>The option may not be modified.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_stream_get.3str.html">nng_stream_get(3str)</a>, +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_ipc_options.5.html">nng_ipc_options(5)</a>, +<a href="nng_tcp_options.5.html">nng_tcp_options(5)</a>, +<a href="nng_tls_options.5.html">nng_tls_options(5)</a>, +<a href="nng_stream.5.html">nng_stream(5)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_strerror.3.html b/man/v1.7.2/nng_strerror.3.html new file mode 100644 index 00000000..dbad48a7 --- /dev/null +++ b/man/v1.7.2/nng_strerror.3.html @@ -0,0 +1,82 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_strerror(3) +--- +<h1>nng_strerror(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_strerror - return an error description</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-w"> </span><span class="tok-nf">nng_strerror</span><span class="tok-p">(</span><span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-n">err</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_strerror()</code> returns the human-readable description of the +given error in <code>err</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The returned error message is provided in US English, but in the +future locale-specific strings may be presented instead. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The specific strings associated with specific error messages are +subject to change. +Therefore applications must not depend on the message, +but may use them verbatim when supplying information to end-users, such +as in diagnostic messages or log entries. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns the human-readable error message, terminated +by a <code>NUL</code> byte.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_strfree.3.html b/man/v1.7.2/nng_strfree.3.html new file mode 100644 index 00000000..20d25cbe --- /dev/null +++ b/man/v1.7.2/nng_strfree.3.html @@ -0,0 +1,96 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_strfree(3) +--- +<h1>nng_strfree(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_strfree - free memory</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_strfree</span><span class="tok-p">(</span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">str</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_strfree()</code> function deallocates the string <em>str</em>. +This is equivalent to using <a href="nng_free.3.html"><code>nng_free()</code></a> with +the length of <em>str</em> plus one (for the <code>NUL</code> terminating byte) as +the size.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This should only be used with strings that were allocated +by <a href="nng_strdup.3.html"><code>nng_strdup()</code></a> or +<a href="nng_alloc.3.html"><code>nng_alloc()</code></a>. +In all cases, the allocation size of the string must be the same +as <code>strlen(<em>str</em>) + 1</code>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Consequently, if the a string created with +<a href="nng_strdup.3.html"><code>nng_strdup()</code></a> is modified to be shorter, then +it is incorrect to call this function. +(The <a href="nng_free.3.html"><code>nng_free()</code></a> function can be used instead in that +case, using the length of the original string plus one for the size.) +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_alloc.3.html">nng_alloc(3)</a>, +<a href="nng_free.3.html">nng_free(3)</a>, +<a href="nng_strdup.3.html">nng_strdup(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_sub.7.html b/man/v1.7.2/nng_sub.7.html new file mode 100644 index 00000000..b9dcb2ae --- /dev/null +++ b/man/v1.7.2/nng_sub.7.html @@ -0,0 +1,153 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_sub(7) +--- +<h1>nng_sub(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_sub - subscriber protocol</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/pubsub0/sub.h></span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>sub</em> protocol is one half of a publisher/subscriber pattern. +In this pattern, a publisher sends data, which is broadcast to all subscribers. +The subscribing applications only see the data to which they have subscribed.</p> +</div> +<div class="paragraph"> +<p>The <em>sub</em> protocol is the subscriber side, and the +<a href="nng_pub.7.html"><em>pub</em></a> protocol is the publisher side.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +In this implementation, the publisher delivers all messages to all +subscribers. +The subscribers maintain their own subscriptions, and filter them locally. +Thus, this pattern should not be used in an attempt to +reduce bandwidth consumption. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The topics that subscribers subscribe to is just the first part of +the message body. +Applications should construct their messages accordingly.</p> +</div> +<div class="sect2"> +<h3 id="_socket_operations">Socket Operations</h3> +<div class="paragraph"> +<p>The <a href="nng_sub_open.3.html"><code>nng_sub0_open()</code></a> functions create a subscriber socket. +This socket may be used to receive messages, but is unable to send them. +Attempts to send messages will result in <code>NNG_ENOTSUP</code>.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_versions">Protocol Versions</h3> +<div class="paragraph"> +<p>Only version 0 of this protocol is supported. +(At the time of writing, no other versions of this protocol have been defined.)</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_options">Protocol Options</h3> +<div class="paragraph"> +<p>The following protocol-specific options are available.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_SUB_SUBSCRIBE</code></dt> +<dd> +<p>This option registers a topic that the subscriber is interested in. +The option is write-only, and takes an array of bytes, of arbitrary size. +Each incoming message is checked against the list of subscribed topics. +If the body begins with the entire set of bytes in the topic, then the +message is accepted. If no topic matches, then the message is +discarded.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This option is a byte array. Thus if you use +<a href="nng_setopt.3.html"><code>nng_setopt_string()</code></a> the <code>NUL</code> terminator byte will +be included in the topic. +If that isn’t desired, consider using +<a href="nng_setopt.3.html"><code>nng_setopt()</code></a> and using <code>strlen()</code> of the topic +as the topic size. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +To receive all messages, an empty topic (zero length) can be used. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>NNG_OPT_SUB_UNSUBSCRIBE</code></dt> +<dd> +<p>This option, also read-only, removes a topic from the subscription list. +Note that if the topic was not previously subscribed to with +<code>NNG_OPT_SUB_SUBSCRIBE</code> then an <code>NNG_ENOENT</code> error will result.</p> +</dd> +<dt class="hdlist1"><code>NNG_OPT_SUB_PREFNEW</code></dt> +<dd> +<p>(<code>bool</code>) +This read/write option specifies the behavior of the subscriber when the queue is full. +When <code>true</code> (the default), the subscriber will make room in the queue by removing the oldest message. +When <code>false</code>, the subscriber will reject messages if the message queue does not have room.</p> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_headers">Protocol Headers</h3> +<div class="paragraph"> +<p>The <em>sub</em> protocol has no protocol-specific headers.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sub_open.3.html">nng_sub_open(3)</a>, +<a href="nng_pub.7.html">nng_pub(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_sub_open.3.html b/man/v1.7.2/nng_sub_open.3.html new file mode 100644 index 00000000..f30f9ba0 --- /dev/null +++ b/man/v1.7.2/nng_sub_open.3.html @@ -0,0 +1,87 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_sub_open(3) +--- +<h1>nng_sub_open(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_sub_open - create sub socket</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/pubsub0/sub.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_sub0_open</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_sub0_open_raw</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_sub0_open()</code> function creates a <a href="nng_sub.7.html"><em>sub</em></a> version 0 +<a href="nng_socket.5.html">socket</a> and returns it at the location pointed to by <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_sub0_open_raw()</code> function creates a <a href="nng_sub.7.html"><em>sub</em></a> version 0 +<a href="nng_socket.5.html">socket</a> in +<a href="nng.7.html#raw_mode">raw</a> mode and returns it at the location pointed to by <em>s</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng_pub.7.html">nng_pub(7)</a>, +<a href="nng_sub.7.html">nng_sub(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_surveyor.7.html b/man/v1.7.2/nng_surveyor.7.html new file mode 100644 index 00000000..9cea4af8 --- /dev/null +++ b/man/v1.7.2/nng_surveyor.7.html @@ -0,0 +1,207 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_surveyor(7) +--- +<h1>nng_surveyor(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_surveyor - surveyor protocol</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/survey0/survey.h></span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>surveyor</em> protocol is one half of a survey pattern. +In this pattern, a surveyor sends a survey, which is broadcast to all +peer respondents. +The respondents then have a chance to reply (but are not obliged to reply). +The survey itself is a timed event, so that responses +received after the survey has finished are discarded.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This protocol is useful in solving voting problems, such as +leader election in cluster configurations, as well as certain kinds of +service discovery problems. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The <em>surveyor</em> protocol is the surveyor side, and the +<a href="nng_respondent.7.html"><em>respondent</em></a> protocol is the respondent side.</p> +</div> +<div class="sect2"> +<h3 id="_socket_operations">Socket Operations</h3> +<div class="paragraph"> +<p>The <a href="nng_surveyor_open.3.html"><code>nng_surveyor0_open()</code></a> +functions create a surveyor socket. +This socket may be used to send messages (surveys), and then to receive replies. +A reply can only be received after sending a survey. +A surveyor can normally expect to receive at most one reply from each responder. +(Messages can be duplicated in some topologies, +so there is no guarantee of this.)</p> +</div> +<div class="paragraph"> +<p>Attempts to receive on a socket with no outstanding survey will result +in <code>NNG_ESTATE</code>. +If the survey times out while the surveyor is waiting +for replies, then the result will be <code>NNG_ETIMEDOUT</code>.</p> +</div> +<div class="paragraph"> +<p>Only one survey can be outstanding at a time; sending another survey will +cancel the prior one, and any responses from respondents from the prior +survey that arrive after this will be discarded.</p> +</div> +<div class="paragraph"> +<p><a href="nng.7.html#raw_mode">Raw</a> mode sockets ignore all these restrictions.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_context_operations">Context Operations</h3> +<div class="paragraph"> +<p>This protocol supports the creation of <a href="nng_ctx.5.html">contexts</a> for concurrent +use cases using <a href="nng_ctx_open.3.html"><code>nng_ctx_open()</code></a>.</p> +</div> +<div class="paragraph"> +<p>Each context can initiate its own surveys, and it will receive only +responses to its own outstanding surveys. +Other contexts on the same socket may have overlapping surveys +operating at the same time.</p> +</div> +<div class="paragraph"> +<p>Each of these may have their own timeouts established with +<code>NNG_OPT_SURVEYOR_SURVEYTIME</code>.</p> +</div> +<div class="paragraph"> +<p>Additionally, sending a survey on a context will only cancel an outstanding +survey on the same context.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Due to the best-effort nature of this protocol, if too may contexts +are attempting to perform surveys simultaneously, it is possible for either +individual outgoing surveys or incoming responses to be lost. +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_versions">Protocol Versions</h3> +<div class="paragraph"> +<p>Only version 0 of this protocol is supported. +(At the time of writing, no other versions of this protocol have been defined. +An earlier and incompatible version of the protocol was used in older +pre-releases of +<a href="http://nanomsg.org">nanomsg</a>, but was not released in any production +version.)</p> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_options">Protocol Options</h3> +<div class="paragraph"> +<p>The following protocol-specific options is available.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_SURVEYOR_SURVEYTIME</code></dt> +<dd> +<p>(<a href="nng_duration.5.html"><code>nng_duration</code></a>) Duration of surveys. +When a new survey is started, a timer of this duration is also started. +Any responses arriving this time will be discarded. +Attempts to receive +after the timer expires with no other surveys started will result in +<code>NNG_ESTATE</code>. +Attempts to receive when this timer expires will result in <code>NNG_ETIMEDOUT</code>.</p> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_headers">Protocol Headers</h3> +<div class="paragraph"> +<p> +This form uses a stack of 32-bit big-endian identifiers. +There <strong>must</strong> be at least one identifier, the <em>survey ID</em>, which will be the +last element in the array, and <strong>must</strong> have the most significant bit set.</p> +</div> +<div class="paragraph"> +<p>There may be additional <em>peer ID</em>s preceding the survey ID. +These will be distinguishable from the survey ID by having their most +significant bit clear.</p> +</div> +<div class="paragraph"> +<p>When a survey message is received by a forwarding node (see +<a href="nng_device.3.html"><code>nng_device()</code></a>), the forwarding node prepends a +32-bit peer ID (which <strong>must</strong> have the most significant bit clear), +which is the forwarder’s way of identifying the directly connected +peer from which it received the message. +(This peer ID, except for the +most significant bit, has meaning only to the forwarding node itself.)</p> +</div> +<div class="paragraph"> +<p>It may help to think of prepending a peer ID as pushing a peer ID onto the +front of the stack of headers for the message. +(It will use the peer ID +it popped from the front to determine the next intermediate destination +for the response.)</p> +</div> +<div class="paragraph"> +<p>When a response message is created, it is created using the same headers +that the survey contained.</p> +</div> +<div class="paragraph"> +<p>A forwarding node can pop the peer ID it originally pushed on the +message, stripping it from the front of the message as it does so.</p> +</div> +<div class="paragraph"> +<p>When the response finally arrives back at the initiating surveyor, it +should have only a single element in the message, which will be the +survey ID it originally used for the request.</p> +</div> +<div class="paragraph"> +<p>More detail can be found in the +<a href="https://github.com/nanomsg/nanomsg/blob/master/rfc/sp-surveyor-01.txt">RFC sp-surveyor-01</a> +document.</p> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_surveyor_open.3.html">nng_surveyor_open(3)</a>, +<a href="nng_respondent.7.html">nng_respondent(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_surveyor_open.3.html b/man/v1.7.2/nng_surveyor_open.3.html new file mode 100644 index 00000000..42d366ad --- /dev/null +++ b/man/v1.7.2/nng_surveyor_open.3.html @@ -0,0 +1,88 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_surveyor_open(3) +--- +<h1>nng_surveyor_open(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_surveyor_open - create surveyor socket</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/protocol/survey0/survey.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_surveyor0_open</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_surveyor0_open_raw</span><span class="tok-p">(</span><span class="tok-n">nng_socket</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">s</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_surveyor0_open()</code> function creates a <a href="nng_surveyor.7.html"><em>surveyor</em></a> +version 0 <a href="nng_socket.5.html">socket</a> and returns it at the location +pointed to by <em>s</em>.</p> +</div> +<div class="paragraph"> +<p>The <code>nng_surveyor0_open_raw()</code> function creates a <a href="nng_surveyor.7.html"><em>surveyor</em></a> +version 0 <a href="nng_socket.5.html">socket</a> in +<a href="nng.7.html#raw_mode">raw</a> mode and returns it at the location pointed to by <em>s</em>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>These functions return 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The protocol is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_socket.5.html">nng_socket(5)</a>, +<a href="nng_respondent.7.html">nng_respondent(7)</a>, +<a href="nng_surveyor.7.html">nng_surveyor(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tcp.7.html b/man/v1.7.2/nng_tcp.7.html new file mode 100644 index 00000000..0e11f220 --- /dev/null +++ b/man/v1.7.2/nng_tcp.7.html @@ -0,0 +1,182 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tcp(7) +--- +<h1>nng_tcp(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tcp - TCP/IP transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/tcp/tcp.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_tcp_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>tcp</em> transport provides communication support between +sockets across a TCP/IP network. +Both IPv4 and IPv6 are supported when the underlying platform also supports it.</p> +</div> +<div class="sect2"> +<h3 id="_registration">Registration</h3> +<div class="paragraph"> +<p>This transport is generally built-in to the core of <em>NNG</em>, so +no extra steps to use it should be necessary.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_uri_format">URI Format</h3> +<div class="paragraph"> +<p> +This transport uses URIs using the scheme <code>tcp://</code>, followed by +an IP address or hostname, followed by a colon and finally a +TCP port number. +For example, to contact port 80 on the localhost either of the following URIs +could be used: <code>tcp://127.0.0.1:80</code> or <code>tcp://localhost:80</code>.</p> +</div> +<div class="paragraph"> +<p>A URI may be restricted to IPv6 using the scheme <code>tcp6://</code>, and may +be restricted to IPv4 using the scheme <code>tcp4://</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Specifying <code>tcp6://</code> may not prevent IPv4 hosts from being used with +IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with +listeners. +The details of this varies across operating systems. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Both <code>tcp6://</code> and <code>tcp4://</code> are specific to <em>NNG</em>, and might not +be understood by other implementations. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +We recommend using either numeric IP addresses, or names that are +specific to either IPv4 or IPv6 to prevent confusion and surprises. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>When specifying IPv6 addresses, the address must be enclosed in +square brackets (<code>[]</code>) to avoid confusion with the final colon +separating the port.</p> +</div> +<div class="paragraph"> +<p>For example, the same port 80 on the IPv6 loopback address (<code>::1</code>) would +be specified as <code>tcp://[::1]:80</code>.</p> +</div> +<div class="paragraph"> +<p>The special value of 0 (<code>INADDR_ANY</code>) +can be used for a listener to indicate that it should listen on all +interfaces on the host. +A short-hand for this form is to either omit the address, or specify +the asterisk (<code>*</code>) character. +For example, the following three URIs are all equivalent, +and could be used to listen to port 9999 on the host:</p> +</div> +<div class="olist arabic"> +<ol class="arabic"> +<li> +<p><code>tcp://0.0.0.0:9999</code></p> +</li> +<li> +<p><code>tcp://*:9999</code></p> +</li> +<li> +<p><code>tcp://:9999</code></p> +</li> +</ol> +</div> +<div class="paragraph"> +<p>The entire URI must be less than <code>NNG_MAXADDRLEN</code> bytes long.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_socket_address">Socket Address</h3> +<div class="paragraph"> +<p>When using an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> structure, +the actual structure is either of type +<a href="nng_sockaddr_in.5.html"><code>nng_sockaddr_in</code></a> (for IPv4) or +<a href="nng_sockaddr_in6.5.html"><code>nng_sockaddr_in6</code></a> (for IPv6).</p> +</div> +</div> +<div class="sect2"> +<h3 id="_transport_options">Transport Options</h3> +<div class="paragraph"> +<p>The following transport options are supported by this transport, +where supported by the underlying platform.</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><a href="nng_options.5.html#NNG_OPT_LOCADDR"><code>NNG_OPT_LOCADDR</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_REMADDR"><code>NNG_OPT_REMADDR</code></a></p> +</li> +<li> +<p><a href="nng_tcp_options.5.html#NNG_OPT_TCP_KEEPALIVE"><code>NNG_OPT_TCP_KEEPALIVE</code></a></p> +</li> +<li> +<p><a href="nng_tcp_options.5.html#NNG_OPT_TCP_NODELAY"><code>NNG_OPT_TCP_NODELAY</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_URL"><code>NNG_OPT_URL</code></a></p> +</li> +</ul> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng_sockaddr_in.5.html">nng_sockaddr_in(5)</a>, +<a href="nng_sockaddr_in6.5.html">nng_sockaddr_in6(5)</a>, +<a href="nng_tcp_options.5.html">nng_tcp_options(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tcp_options.5.html b/man/v1.7.2/nng_tcp_options.5.html new file mode 100644 index 00000000..4bc8ffc1 --- /dev/null +++ b/man/v1.7.2/nng_tcp_options.5.html @@ -0,0 +1,192 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tcp_options(5) +--- +<h1>nng_tcp_options(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tcp_options - TCP-specific options</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-cp">#define NNG_OPT_TCP_NODELAY "tcp-nodelay"</span> +<span class="tok-cp">#define NNG_OPT_TCP_KEEPALIVE "tcp-keepalive"</span> +<span class="tok-cp">#define NNG_OPT_TCP_BOUND_PORT "tcp-bound-port"</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This page documents the various standard options that can be set or +retrieved on objects using TCP.</p> +</div> +<div class="paragraph"> +<p>The option names should always be used by their symbolic definitions.</p> +</div> +<div class="paragraph"> +<p>In the following list of options, the name of the option is supplied, +along with the data type of the underlying value.</p> +</div> +<div class="paragraph"> +<p>Some options are only meaningful or supported in certain contexts, or may +have other access restrictions. +An attempt has been made to include details about such restrictions in the +description of the option.</p> +</div> +<div class="paragraph"> +<p>The following options are generally application to objects making use of +TCP/IP communications.</p> +</div> +<div class="sect2"> +<h3 id="_tcp_options">TCP Options</h3> +<div id="NNG_OPT_TCP_NODELAY" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_TCP_NODELAY</code></dt> +<dd> +<p>(<code>bool</code>) +This option is used to disable (or enable) the use of Nagle’s algorithm +for TCP connections.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This setting may apply to transports that are built on top of TCP. +See the transport documentation for each transport for details. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>When <code>true</code> (the default), messages are sent immediately by the underlying +TCP stream without waiting to gather more data.</p> +</div> +<div class="paragraph"> +<p>When <code>false</code>, Nagle’s algorithm is enabled, and the TCP stream may +wait briefly in attempt to coalesce messages. +Nagle’s algorithm is useful on low-bandwidth connections to reduce overhead, +but it comes at a cost to latency.</p> +</div> +<div class="paragraph"> +<p>When used on a dialer or a listener, the value affects how newly +created connections will be configured.</p> +</div> +</dd> +</dl> +</div> +<div id="NNG_OPT_TCP_KEEPALIVE" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_TCP_KEEPALIVE</code></dt> +<dd> +<p>(<code>bool</code>) +This option is used to enable the sending of keep-alive messages on +the underlying TCP stream. +This option is <code>false</code> by default.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This setting may apply to transports that are built on top of TCP. +See the transport documentation for each transport for details. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>When enabled, if no messages are seen for a period of time, then +a zero length TCP message is sent with the ACK flag set in an attempt +to tickle some traffic from the peer. +If none is still seen (after some platform-specific number of retries and +timeouts), then the remote peer is presumed dead, and the connection is closed.</p> +</div> +<div class="paragraph"> +<p>When used on a dialer or a listener, the value affects how newly +created connections will be configured.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This option has two purposes. +First, it can be used to detect dead peers on an otherwise quiescent network. +Second, it can be used to keep connection table entries in NAT and other +middleware from being expiring due to lack of activity. +</td> +</tr> +</table> +</div> +</dd> +</dl> +</div> +<div id="NNG_OPT_TCP_BOUND_PORT" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_TCP_BOUND_PORT</code></dt> +<dd> +<p>(<code>int</code>) +This option is available on listeners, after the listern has bound to +a port, and provides the port bound to in native byte order. +This is most useful when using a listener with an ephemeral port +(configured by using port 0 at configuration time), as it allows +the caller to determine the actual ephemeral port that was chosen by the +system. +While the value is of type <code>int</code>, it will be a legal TCP port number, that +is a value between 1 and 65535, inclusive.</p> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_inherited_options">Inherited Options</h3> +<div class="paragraph"> +<p>Generally, the following option values are also available for TCP objects, +when appropriate for the context:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><a href="nng_options.5.html#NNG_OPT_LOCADDR"><code>NNG_OPT_LOCADDR</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_REMADDR"><code>NNG_OPT_REMADDR</code></a></p> +</li> +</ul> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_tcp_dialer_getopt.3tcp.html">nng_tcp_dialer_getopt(3tcp)</a>, +<a href="nng_tcp_dialer_setopt.3tcp.html">nng_tcp_dialer_setopt(3tcp)</a>, +<a href="nng_tcp_getopt.3tcp.html">nng_tcp_getopt(3tcp)</a>, +<a href="nng_tcp_listener_getopt.3tcp.html">nng_tcp_listener_getopt(3tcp)</a>, +<a href="nng_tcp_listener_setopt.3tcp.html">nng_tcp_listener_setopt(3tcp)</a>, +<a href="nng_tcp_setopt.3tcp.html">nng_tcp_setopt(3tcp)</a>, +<a href="nng_options.5.html">nng_options(5)</a> +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tcp_register.3.html b/man/v1.7.2/nng_tcp_register.3.html new file mode 100644 index 00000000..db06e17e --- /dev/null +++ b/man/v1.7.2/nng_tcp_register.3.html @@ -0,0 +1,90 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tcp_register(3) +--- +<h1>nng_tcp_register(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tcp_register - register tcp transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/tcp/tcp.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_tcp_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tcp_register()</code> function registers the +<em>tcp</em> transport for use.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The transport is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_tcp.7.html">nng_tcp(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_thread_create.3supp.html b/man/v1.7.2/nng_thread_create.3supp.html new file mode 100644 index 00000000..8e6f45b4 --- /dev/null +++ b/man/v1.7.2/nng_thread_create.3supp.html @@ -0,0 +1,156 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_thread_create(3supp) +--- +<h1>nng_thread_create(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_thread_create - create thread</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_thread</span><span class="tok-w"> </span><span class="tok-n">nng_thread</span><span class="tok-p">;</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_thread_create</span><span class="tok-p">(</span><span class="tok-n">nng_thread</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">thrp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-o">*</span><span class="tok-n">func</span><span class="tok-p">)(</span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-p">),</span><span class="tok-w"> </span><span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">arg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_thread_create()</code> function creates a single thread of execution, +running <em>func</em> with the argument <em>arg</em>. +The thread is started immediately. +A pointer to the thread object is returned in <em>thrp</em>.</p> +</div> +<div class="paragraph"> +<p>The intention of this program is to facilitate writing parallel programs. +Threads created by this program will be based upon the underlying +threading mechanism of the system that <em>NNG</em> is running on. +This may include use of coroutines.</p> +</div> +<div class="paragraph"> +<p>Using threads created by this function can make it easy to write +programs that use simple sequential execution, using functions in the +<em>NNG</em> suite that would otherwise normally wait synchronously for completion.</p> +</div> +<div class="paragraph"> +<p>When the thread is no longer needed, the +<a href="nng_thread_destroy.3supp.html"><code>nng_thread_destroy()</code></a> +function should be used to reap it. +(This function will block waiting for <em>func</em> to return.)</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Thread objects created by this function may not be real system +level threads capable of performing blocking I/O operations using normal blocking +system calls. +If use of blocking system calls is required (not including APIs provided +by the <em>NNG</em> library itself of course), then real OS-specific threads +should be created instead (such as with <code>pthread_create()</code> or similar +functions.) +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Thread objects created by this function cannot be passed +to any system threading functions. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The system may impose limits on the number of threads that can be +created. +Typically applications should not create more than a dozen of these. +If greater concurrency or scalability is needed, consider instead using +an asynchronous model using <a href="nng_aio.5.html"><code>nng_aio</code></a> structures. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Threads can be synchronized using +<a href="nng_mtx_alloc.3supp.html">mutexes</a> and +<a href="nng_cv_alloc.3supp.html">condition variables</a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_cv_alloc.3supp.html">nng_cv_alloc(3supp)</a>, +<a href="nng_mtx_alloc.3supp.html">nng_mtx_alloc(3supp)</a>, +<a href="nng_thread_destroy.3supp.html">nng_thread_destroy(3supp)</a>, +<a href="nng_aio.5.html">nng_aio(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_thread_destroy.3supp.html b/man/v1.7.2/nng_thread_destroy.3supp.html new file mode 100644 index 00000000..a1e3a37f --- /dev/null +++ b/man/v1.7.2/nng_thread_destroy.3supp.html @@ -0,0 +1,75 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_thread_destroy(3supp) +--- +<h1>nng_thread_destroy(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_thread_destroy - reap thread</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_thread_destroy</span><span class="tok-p">(</span><span class="tok-n">nng_thread</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-kr">thread</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_thread_destroy()</code> function reaps the <em>thread</em>. +It waits for the thread function to return, and then deallocates +the resources for the thread.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +Do not call this function from the thread function itself, +or a deadlock will occur. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_thread_create.3supp.html">nng_thread_create(3supp)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_thread_set_name.3supp.html b/man/v1.7.2/nng_thread_set_name.3supp.html new file mode 100644 index 00000000..9aa34b4d --- /dev/null +++ b/man/v1.7.2/nng_thread_set_name.3supp.html @@ -0,0 +1,79 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_thread_set_name(3supp) +--- +<h1>nng_thread_set_name(3supp)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_thread_set_name - set thread name</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/util/platform.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_thread_set_name</span><span class="tok-p">(</span><span class="tok-n">nng_thread</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-kr">thread</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">name</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_thread_set_name()</code> function attempts to set the name for the <em>thread</em> to <em>name</em>.</p> +</div> +<div class="paragraph"> +<p>If <em>thread</em> is <code>NULL</code>, then the name is set for the current thread.</p> +</div> +<div class="paragraph"> +<p>Support for this, and how names are exposed, varies between platform implementations. +This function is intended to facilitate debugging applications that may have many threads.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Internal threads created by <em>NNG</em> will have names beginning with <code>nng:</code>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_thread_create.3supp.html">nng_thread_create(3supp)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls.7.html b/man/v1.7.2/nng_tls.7.html new file mode 100644 index 00000000..4dce5f34 --- /dev/null +++ b/man/v1.7.2/nng_tls.7.html @@ -0,0 +1,266 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls(7) +--- +<h1>nng_tls(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls - TLS transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/tls/tls.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>tls</em> transport provides communication support between +peers across a TCP/IP network using +<a href="https://tools.ietf.org/html/rfc5246">TLS v1.2</a> on top of +<a href="https://tools.ietf.org/html/rfc793">TCP</a>. +Both IPv4 and IPv6 are supported when the underlying platform also supports it.</p> +</div> +<div class="paragraph"> +<p>The protocol details are documented in +<a href="http://nanomsg.org/rfcs/sp-tls-v1.html">TLS Mapping for Scalability Protocols</a>.</p> +</div> +<div class="sect2"> +<h3 id="_registration">Registration</h3> +<div class="paragraph"> +<p>Depending upon how the library was built, it may be necessary to +register the transport by calling +<a href="nng_tls_register.3.html"><code>nng_tls_register()</code></a>.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_availability">Availability</h3> +<div class="paragraph"> +<p>The <em>tls</em> transport depends on the use of an external library. +As of this writing, <a href="https://tls.mbed.org/">mbedTLS</a> version 2.0 +or later is required.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Applications may need to add this library (or libraries) to +their link line, particularly when using a statically built +library. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The mbedTLS library uses different licensing terms than +<em>NNG</em> itself; as of this writing it is offered under either +<a href="https://opensource.org/licenses/Apache-2.0">Apache License 2.0</a> or +<a href="https://opensource.org/licenses/gpl-license">GNU GPL</a> terms. +You are responsible for understanding and adhering to the +license terms of any libraries you use. +</td> +</tr> +</table> +</div> +</div> +<div class="sect2"> +<h3 id="_uri_format">URI Format</h3> +<div class="paragraph"> +<p> +This transport uses URIs using the scheme <code>tls+tcp://</code>, followed by +an IP address or hostname, followed by a colon and finally a +TCP port number. +For example, to contact port 4433 on the localhost +either of the following URIs could be used: <code>tls+tcp://127.0.0.1:4433</code> or +<code>tls+tcp://localhost:4433</code>.</p> +</div> +<div class="paragraph"> +<p>A URI may be restricted to IPv6 using the scheme <code>tls+tcp6://</code>, and may +be restricted to IPv4 using the scheme <code>tls+tcp4://</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Specifying <code>tls+tcp6://</code> may not prevent IPv4 hosts from being used with +IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with +listeners. +The details of this varies across operating systems. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Both <code>tls+tcp6://</code> and <code>tls+tcp4://</code> are specific to <em>NNG</em>, and may not +be understood by other implementations. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +We recommend using either numeric IP addresses, or names that are +specific to either IPv4 or IPv6 to prevent confusion and surprises. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>When specifying IPv6 addresses, the address must be enclosed in +square brackets (<code>[]</code>) to avoid confusion with the final colon +separating the port.</p> +</div> +<div class="paragraph"> +<p>For example, the same port 4433 on the IPv6 loopback address ('::1') would +be specified as <code>tls+tcp://[::1]:4433</code>.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Certificate validation generally works when using names +rather than IP addresses. +This transport automatically uses the name supplied in the URL when validating +the certificate supplied by the server. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The special value of 0 (<code>INADDR_ANY</code>) can be used for a listener +to indicate that it should listen on all interfaces on the host. +A short-hand for this form is to either omit the address, or specify +the asterisk (<code>*</code>) character. +For example, the following three URIs are all equivalent, +and could be used to listen to port 9999 on the host:</p> +</div> +<div class="olist arabic"> +<ol class="arabic"> +<li> +<p><code>tls+tcp://0.0.0.0:9999</code></p> +</li> +<li> +<p><code>tls+tcp://*:9999</code></p> +</li> +<li> +<p><code>tls+tcp://:9999</code></p> +</li> +</ol> +</div> +<div class="paragraph"> +<p>The entire URI must be less than <code>NNG_MAXADDRLEN</code> bytes long.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_socket_address">Socket Address</h3> +<div class="paragraph"> +<p>When using an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> structure, +the actual structure is either of type +<a href="nng_sockaddr_in.5.html"><code>nng_sockaddr_in</code></a> (for IPv4) or +<a href="nng_sockaddr_in6.5.html"><code>nng_sockaddr_in6</code></a> (for IPv6).</p> +</div> +</div> +<div class="sect2"> +<h3 id="_transport_options">Transport Options</h3> +<div class="paragraph"> +<p>The following transport options are available. +Note that setting these must be done before the transport is started.</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><a href="nng_options.5.html#NNG_OPT_LOCADDR"><code>NNG_OPT_LOCADDR</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_REMADDR"><code>NNG_OPT_REMADDR</code></a></p> +</li> +<li> +<p><a href="nng_tcp_options.5.html#NNG_OPT_TCP_KEEPALIVE"><code>NNG_OPT_TCP_KEEPALIVE</code></a></p> +</li> +<li> +<p><a href="nng_tcp_options.5.html#NNG_OPT_TCP_NODELAY"><code>NNG_OPT_TCP_NODELAY</code></a></p> +</li> +<li> +<p><a href="nng_tls_options.5.html#NNG_OPT_TLS_AUTH_MODE"><code>NNG_OPT_TLS_AUTH_MODE</code></a></p> +</li> +<li> +<p><a href="nng_tls_options.5.html#NNG_OPT_TLS_CA_FILE"><code>NNG_OPT_TLS_CA_FILE</code></a></p> +</li> +<li> +<p><a href="nng_tls_options.5.html#NNG_OPT_TLS_CERT_KEY_FILE"><code>NNG_OPT_TLS_CERT_KEY_FILE</code></a></p> +</li> +<li> +<p><a href="nng_tls_options.5.html#NNG_OPT_TLS_CONFIG"><code>NNG_OPT_TLS_CONFIG</code></a></p> +</li> +<li> +<p><a href="nng_tls_options.5.html#NNG_OPT_TLS_VERIFIED"><code>NNG_OPT_TLS_VERIFIED_</code></a></p> +</li> +<li> +<p><a href="nng_tls_options.5.html#NNG_OPT_TLS_PEER_CN"><code>NNG_OPT_TLS_PEER_CN</code></a></p> +</li> +<li> +<p><a href="nng_tls_options.5.html#NNG_OPT_TLS_PEER_ALT_NAMES"><code>NNG_OPT_TLS_PEER_ALT_NAMES</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_URL"><code>NNG_OPT_URL</code></a></p> +</li> +</ul> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a> +<a href="nng_options.5.html">nng_options(5)</a>, +<a href="nng_sockaddr_in.5.html">nng_sockaddr_in(5)</a>, +<a href="nng_sockaddr_in6.5.html">nng_sockaddr_in6(5)</a>, +<a href="nng_tcp_options.5.html">nng_tcp_options(5)</a>, +<a href="nng_tls_config.5.html">nng_tls_config(5)</a>, +<a href="nng_tls_options.5.html">nng_tls_options(5)</a>, +<a href="nng.7.html">nng(7)</a>,</p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_config.5.html b/man/v1.7.2/nng_tls_config.5.html new file mode 100644 index 00000000..5d640ebf --- /dev/null +++ b/man/v1.7.2/nng_tls_config.5.html @@ -0,0 +1,69 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_config(5) +--- +<h1>nng_tls_config(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_config - TLS configuration object</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_tls_config</span><span class="tok-w"> </span><span class="tok-n">nng_tls_config</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>An <code>nng_tls_config</code> represents a single TLS configuration object, which +can be used to configure TLS servers and clients.</p> +</div> +<div class="paragraph"> +<p>Configuration data includes details such as certificate chains used for +validation of remote peers, local key and certificate material, server +names, and so forth. +Additionally, a configuration can be used either in client mode, or in +server mode.</p> +</div> +<div class="paragraph"> +<p>Configuration objects may be shared, and are reference counted. +However once a configuration is used, it enters a read-only state that +precludes further modifications to the configuration.</p> +</div> +<div class="paragraph"> +<p>Messages are allocated using the +<a href="nng_tls_config_alloc.3tls.html"><code>nng_tls_config_alloc()</code></a> +function, and are deallocated using the +<a href="nng_tls_config_free.3tls.html"><code>nng_tls_config_free()</code></a> +function.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_tls_config_auth_mode.3tls.html">nng_tls_config_auth_mode(3tls)</a>, +<a href="nng_tls_config_ca_chain.3tls.html">nng_tls_config_ca_chain(3tls)</a>, +<a href="nng_tls_config_own_cert.3tls.html">nng_tls_config_own_cert(3tls)</a>, +<a href="nng_tls_config_free.3tls.html">nng_tls_config_free(3tls)</a>, +<a href="nng_tls_config_hold.3tls.html">nng_tls_config_hold(3tls)</a>, +<a href="nng_tls_config_server_name.3tls.html">nng_tls_config_server_name(3tls)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_config_alloc.3tls.html b/man/v1.7.2/nng_tls_config_alloc.3tls.html new file mode 100644 index 00000000..157fa60a --- /dev/null +++ b/man/v1.7.2/nng_tls_config_alloc.3tls.html @@ -0,0 +1,121 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_config_alloc(3tls) +--- +<h1>nng_tls_config_alloc(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_config_alloc - allocate TLS configuration object</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-n">nng_tls_mode</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_TLS_MODE_CLIENT</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_TLS_MODE_SERVER</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_tls_mode</span><span class="tok-p">;</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_config_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">cfgp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_tls_mode</span><span class="tok-w"> </span><span class="tok-n">mode</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_config_alloc()</code> function creates a newly initialized +<a href="https://tools.ietf.org/html/rfc5246">Transport Layer Security</a>) +configuration object, and stores a pointer to it in the value pointed +to by <em>cfgp</em>.</p> +</div> +<div class="paragraph"> +<p>This object is initialized for use when acting as either a +client (<code>NNG_TLS_MODE_CLIENT</code>) or as a server (<code>NNG_TLS_MODE_SERVER</code>), +depending on the value of <em>mode</em>.</p> +</div> +<div class="paragraph"> +<p>A TLS object can be further modified by functions that set the security +keys used, peer certificates, protocol policies, and so forth.</p> +</div> +<div class="paragraph"> +<p>A single TLS configuration object can be used with multiple TLS streams +or services. +The underlying system uses reference counting to ensure +that object is not inadvertently freed while in use.</p> +</div> +<div class="paragraph"> +<p>A configuration object created with <code>nng_tls_config_alloc()</code> starts +with a reference count of one. +The reference count may be incremented using +<a href="nng_tls_config_hold.3tls.html"><code>nng_tls_config_hold()</code></a> and may be +decremented with +<a href="nng_tls_config_free.3tls.html"><code>nng_tls_config_free()</code></a>.</p> +</div> +<div class="paragraph"> +<p>Also note that a TLS configuration object becomes read-only after it +is first used with a service. +After this points, attempts to apply +further changes to the configuration will result in <code>NNG_EBUSY</code>.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>mode</em> was specified.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_tls_config_auth_mode.3tls.html">nng_tls_config_auth_mode(3tls)</a>, +<a href="nng_tls_config_ca_chain.3tls.html">nng_tls_config_ca_chain(3tls)</a>, +<a href="nng_tls_config_own_cert.3tls.html">nng_tls_config_own_cert(3tls)</a>, +<a href="nng_tls_config_free.3tls.html">nng_tls_config_free(3tls)</a>, +<a href="nng_tls_config_hold.3tls.html">nng_tls_config_hold(3tls)</a>, +<a href="nng_tls_config_server_name.3tls.html">nng_tls_config_server_name(3tls)</a>, +<a href="nng_tls_config.5.html">nng_tls_config(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_config_auth_mode.3tls.html b/man/v1.7.2/nng_tls_config_auth_mode.3tls.html new file mode 100644 index 00000000..13dcf129 --- /dev/null +++ b/man/v1.7.2/nng_tls_config_auth_mode.3tls.html @@ -0,0 +1,122 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_config_auth_mode(3tls) +--- +<h1>nng_tls_config_auth_mode(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_config_auth_mode - configure authentication mode</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-n">nng_tls_auth_mode</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_TLS_AUTH_MODE_NONE</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_TLS_AUTH_MODE_OPTIONAL</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_TLS_AUTH_MODE_REQUIRED</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_tls_auth_mode</span><span class="tok-p">;</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_config_auth_mode</span><span class="tok-p">(</span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cfg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_tls_auth_mode</span><span class="tok-w"> </span><span class="tok-n">mode</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_config_auth_mode()</code> function configures the authentication mode +to be used for TLS sessions using this configuration object.</p> +</div> +<div class="paragraph"> +<p>The possible modes are:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_TLS_AUTH_MODE_NONE</code></dt> +<dd> +<p>No authentication of the TLS peer is performed. +This is the default for +TLS servers, which most typically do not authenticate their clients.</p> +</dd> +<dt class="hdlist1"><code>NNG_TLS_AUTH_MODE_OPTIONAL</code></dt> +<dd> +<p>If a certificate is presented by the peer, then it is validated. +However, if the peer does not present a valid certificate, +then the session is allowed to proceed without authentication.</p> +</dd> +<dt class="hdlist1"><code>NNG_TLS_AUTH_MODE_REQUIRED</code></dt> +<dd> +<p>A check is made to ensure that the peer has presented a valid certificate +used for the session. +If the peer’s certificate is invalid or missing, then the session is refused. +This is the default for clients.</p> +</dd> +</dl> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>mode</em> was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EBUSY</code> +</td> +<td class="hdlist2"> +<p>The configuration <em>cfg</em> is already in use, and cannot be modified.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_tls_config_ca_chain.3tls.html">nng_tls_config_ca_chain(3tls)</a>, +<a href="nng_tls_config_ca_file.3tls.html">nng_tls_config_ca_file(3tls)</a>, +<a href="nng_tls_config_server_name.3tls.html">nng_tls_config_server_name(3tls)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_config_ca_chain.3tls.html b/man/v1.7.2/nng_tls_config_ca_chain.3tls.html new file mode 100644 index 00000000..a1980f98 --- /dev/null +++ b/man/v1.7.2/nng_tls_config_ca_chain.3tls.html @@ -0,0 +1,126 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_config_ca_chain(3tls) +--- +<h1>nng_tls_config_ca_chain(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_config_ca_chain - configure certificate authority certificate chain</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_config_ca_chain</span><span class="tok-p">(</span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cfg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">chain</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">crl</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_config_ca_chain()</code> function configures a certificate or +certificate chain to be used when validating peers using the configuration +<em>cfg</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Certificates <strong>must</strong> be configured when using the authentication mode +<code>NNG_TLS_AUTH_MODE_REQUIRED</code>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This function may be called multiple times, to add additional chains +to a configuration, without affecting those added previously. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>The certificates located in <em>chain</em> must be a zero-terminated C string in +<a href="https://tools.ietf.org/html/rfc7468">PEM</a> format. +Multiple certificates may appear concatenated together, +with the leaf certificate listed first.</p> +</div> +<div class="paragraph"> +<p>The <em>crl</em> may be <code>NULL</code>, or may also be a C string containing a PEM format +certificate revocation list for the associated authority.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EBUSY</code> +</td> +<td class="hdlist2"> +<p>The configuration <em>cfg</em> is already in use, and cannot be modified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>chain</em> or <em>crl</em> was supplied.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(.3tls)</a>, +<a href="nng_tls_config_auth_mode.3tls.html">nng_tls_config_auth_mode(.3tls)</a>, +<a href="nng_tls_config_ca_file.3tls.html">nng_tls_config_ca_file(.3tls)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_config_ca_file.3tls.html b/man/v1.7.2/nng_tls_config_ca_file.3tls.html new file mode 100644 index 00000000..8a3d679c --- /dev/null +++ b/man/v1.7.2/nng_tls_config_ca_file.3tls.html @@ -0,0 +1,138 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_config_ca_file(3tls) +--- +<h1>nng_tls_config_ca_file(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_config_ca_file - load certificate authority from file</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_config_ca_file</span><span class="tok-p">(</span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cfg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_config_ca_file()</code> function configures the certificate authority +certificate chain and optional revocation list by loading the certificates +(and revocation list if present) from a single named file. +The file must at least one X.509 certificate in +<a href="https://tools.ietf.org/html/rfc7468">PEM</a> +format, and may contain multiple such certificates, as well as zero or +more PEM CRL objects. +This information is used to validate certificates +that are presented by peers, when using the configuration <em>cfg</em>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Certificates <strong>must</strong> be configured when using the authentication mode +<code>NNG_TLS_AUTH_MODE_REQUIRED</code>. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This function may be called multiple times, to add additional chains +to a configuration, without affecting those added previously. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EBUSY</code> +</td> +<td class="hdlist2"> +<p>The configuration <em>cfg</em> is already in use, and cannot be modified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The contents of <em>path</em> are invalid or do not contain a valid PEM certificate.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOENT</code> +</td> +<td class="hdlist2"> +<p>The file <em>path</em> does not exist.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EPERM</code> +</td> +<td class="hdlist2"> +<p>The file <em>path</em> is not readable.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_tls_config_auth_mode.3tls.html">nng_tls_config_auth_mode(3tls)</a>, +<a href="nng_tls_config_ca_chain.3tls.html">nng_tls_config_ca_chain(3tls)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_config_cert_key_file.3tls.html b/man/v1.7.2/nng_tls_config_cert_key_file.3tls.html new file mode 100644 index 00000000..160411e8 --- /dev/null +++ b/man/v1.7.2/nng_tls_config_cert_key_file.3tls.html @@ -0,0 +1,125 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_config_cert_key_file(3tls) +--- +<h1>nng_tls_config_cert_key_file(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_config_cert_key_file - load own certificate and key from file</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_config_cert_key_file</span><span class="tok-p">(</span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cfg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">path</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">pass</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_config_cert_key_file()</code> function loads a certificate (or +certificate chain) and a private key from the file named by <em>path</em>.</p> +</div> +<div class="paragraph"> +<p>The file must contain both the <a href="https://tools.ietf.org/html/rfc7468">PEM</a> +encoded certificate and associated private key, which will be used when +establishing TLS sessions using <em>cfg</em>. +It may contain additional certificates leading to a validation chain, +with the leaf certificate first. +There is no need to include the self-signed root, as the peer +will need to have that already in order to perform its own validation.</p> +</div> +<div class="paragraph"> +<p>The private key may be encrypted with a password, in which can be supplied in +<em>pass</em>. +The value <code>NULL</code> should be supplied for <em>pass</em> if the key is not encrypted.</p> +</div> +<div class="paragraph"> +<p>On servers, it is possible to call this function multiple times for the +same configuration. +This can be useful for specifying different parameters +to be used for different cryptographic algorithms.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EBUSY</code> +</td> +<td class="hdlist2"> +<p>The configuration <em>cfg</em> is already in use, and cannot be modified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>The contents of <em>path</em> are invalid.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOENT</code> +</td> +<td class="hdlist2"> +<p>The file named by <em>path</em> does not exist.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EPERM</code> +</td> +<td class="hdlist2"> +<p>The file named by <em>path</em> cannot be opened.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_tls_config_own_cert.3tls.html">nng_tls_config_own_cert(3tls)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_config_free.3tls.html b/man/v1.7.2/nng_tls_config_free.3tls.html new file mode 100644 index 00000000..69f3bc45 --- /dev/null +++ b/man/v1.7.2/nng_tls_config_free.3tls.html @@ -0,0 +1,62 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_config_free(3tls) +--- +<h1>nng_tls_config_free(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_config_free - deallocate a TLS configuration object</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_config_free</span><span class="tok-p">(</span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cfg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_config_free()</code> decrements the reference count on the +TLS configuration object pointed to by <em>cfg</em>, and if the resulting +reference count is zero, then deallocates the configuration object.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_config_hold.3tls.html b/man/v1.7.2/nng_tls_config_hold.3tls.html new file mode 100644 index 00000000..b75e3a0e --- /dev/null +++ b/man/v1.7.2/nng_tls_config_hold.3tls.html @@ -0,0 +1,71 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_config_hold(3tls) +--- +<h1>nng_tls_config_hold(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_config_hold - hold TLS configuration object</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_config_alloc</span><span class="tok-p">(</span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cfg</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_config_hold()</code> increments the reference count on +the configuration object named by <em>cfg</em>, thereby preventing it +from being freed while in use.</p> +</div> +<div class="paragraph"> +<p>The hold can be released by calling +<a href="nng_tls_config_free.3tls.html"><code>nng_tls_config_free()</code></a>.</p> +</div> +<div class="paragraph"> +<p>Multiple holds can be placed on a configuration object; the object +will not be freed until the last hold is released.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_tls_config_free.3tls.html">nng_tls_config_free(3tls)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_config_own_cert.3tls.html b/man/v1.7.2/nng_tls_config_own_cert.3tls.html new file mode 100644 index 00000000..1a8fd642 --- /dev/null +++ b/man/v1.7.2/nng_tls_config_own_cert.3tls.html @@ -0,0 +1,110 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_config_own_cert(3tls) +--- +<h1>nng_tls_config_own_cert(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_config_own_cert - configure own certificate and key</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_config_own_cert</span><span class="tok-p">(</span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cfg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cert</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">key</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">pass</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_config_own_cert()</code> function configures a certificate <em>cert</em> +identifying the local side of a TLS connection used with <em>cfg</em>, along with an +associated private or secret key <em>key</em>. +The certificate may be +a chain, with the leaf signer first and the root at the end. The +self-signed certificate at the end can be omitted. +(The client should already +have it, and will have to in order to validate this certificate anyway).</p> +</div> +<div class="paragraph"> +<p>The <em>key</em> may be encrypted with a password, in which can be supplied in <em>pass</em>. +The value <code>NULL</code> should be supplied for <em>pass</em> if the key is not encrypted.</p> +</div> +<div class="paragraph"> +<p>On servers, it is possible to call this function multiple times for the +same configuration. +This can be useful for specifying different parameters +to be used for different cryptographic algorithms.</p> +</div> +<div class="paragraph"> +<p>The certificate located in <em>cert</em> and <em>key</em> must be NUL (<code>\0</code>) terminated C +strings containing +<a href="https://tools.ietf.org/html/rfc7468">PEM</a> formatted material.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EBUSY</code> +</td> +<td class="hdlist2"> +<p>The configuration <em>cfg</em> is already in use, and cannot be modified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid <em>cert</em> or <em>key</em> was supplied.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_tls_config_cert_key_file.3tls.html">nng_tls_config_cert_key_file(3tls)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_config_server_name.3tls.html b/man/v1.7.2/nng_tls_config_server_name.3tls.html new file mode 100644 index 00000000..e59f4cd6 --- /dev/null +++ b/man/v1.7.2/nng_tls_config_server_name.3tls.html @@ -0,0 +1,97 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_config_server_name(3tls) +--- +<h1>nng_tls_config_server_name(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_config_server_name - configure remote server name</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_config_server_name</span><span class="tok-p">(</span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cfg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">name</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_config_server_name()</code> function configures the remote server name +to be used by a client when connection to a server. +The supplied <em>name</em> is used when comparing the identity in the +server’s certificate. +Furthermore, when Server Name Indication (SNI) is used, the <em>name</em> may +be sent to the server as a hint to tell it which of several possible +certificates should be used.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +This function is only useful in configuring client behavior. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EBUSY</code> +</td> +<td class="hdlist2"> +<p>The configuration <em>cfg</em> is already in use, and cannot be modified.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_tls_config_auth_mode.3tls.html">nng_tls_config_auth_mode(3tls)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_config_version.3tls.html b/man/v1.7.2/nng_tls_config_version.3tls.html new file mode 100644 index 00000000..bf21b4e5 --- /dev/null +++ b/man/v1.7.2/nng_tls_config_version.3tls.html @@ -0,0 +1,172 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_config_version(3tls) +--- +<h1>nng_tls_config_version(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_config_version - configure TLS version</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">enum</span><span class="tok-w"> </span><span class="tok-n">nng_tls_version</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-n">NNG_TLS_1_0</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mh">0x301</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_TLS_1_1</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mh">0x302</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_TLS_1_2</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mh">0x303</span><span class="tok-p">,</span> +<span class="tok-w"> </span><span class="tok-n">NNG_TLS_1_3</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-mh">0x304</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_tls_version</span><span class="tok-p">;</span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_config_version</span><span class="tok-p">(</span><span class="tok-n">nng_tls_config</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">cfg</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_tls_version</span><span class="tok-w"> </span><span class="tok-n">min</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_tls_version</span><span class="tok-w"> </span><span class="tok-n">max</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_config_version()</code> function configures the TLS version numbers that may be used when establishing TLS sessions using this configuration object.</p> +</div> +<div class="paragraph"> +<p>The actual set supported range will further be restricted by the versions that the +<a href="nng_tls_engine.5.html">TLS engine</a> supports. +If the TLS engine cannot support any TLS version in the requested range, then <code>NNG_ENOTSUP</code> is returned.</p> +</div> +<div class="paragraph"> +<p>By default (if this function is not called), NNG will attempt to use both TLS v1.2 and TLS v1.3, provided that the TLS engine supports them.</p> +</div> +<div class="paragraph"> +<p>Clients and servers will generally negotiate for the highest mutually supported TLS version.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +As of this writing, we recommend setting the minimum to +<code>NNG_TLS_1_2</code> (TLS v1.2) and the maximum to <code>NNG_TLS_1_3</code> (TLS v1.3). +This gives the best security, while ensuring good interoperability. +Nearly all modern TLS implementations support TLS v1.2. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Support for TLS v1.3 is available via external TLS engines. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The cipher-suites supported by TLS v1.3 are different from earlier versions. +Therefore it may be necessary to generate different certificates. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_caveats">CAVEATS</h2> +<div class="sectionbody"> +<div class="ulist"> +<ul> +<li> +<p>SSL v2.0 and v3.0 are insecure, and not supported in NNG.</p> +</li> +<li> +<p>TLS v1.3 is not supported by the default <em>Mbed TLS</em> engine at this time.</p> +</li> +<li> +<p>Some TLS engines may not support limiting the maximum version.</p> +</li> +<li> +<p>TLS v1.3 Zero Round Trip Time (0-RTT) is not supported in NNG.</p> +</li> +<li> +<p>Session resumption is not supported in NNG (for any TLS version).</p> +</li> +<li> +<p>TLS PSK support is not supported in NNG. (This is a limitation planned to be addressed.)</p> +</li> +</ul> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid version was specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EBUSY</code> +</td> +<td class="hdlist2"> +<p>The configuration <em>cfg</em> is already in use, and cannot be modified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The TLS implementation cannot support any version in the requested range.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_tls_engine.5.html">nng_tls_engine(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_engine.5.html b/man/v1.7.2/nng_tls_engine.5.html new file mode 100644 index 00000000..1e778d45 --- /dev/null +++ b/man/v1.7.2/nng_tls_engine.5.html @@ -0,0 +1,61 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_engine(5) +--- +<h1>nng_tls_engine(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_engine - TLS engine implementation</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> +<span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/engine.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_tls_engine_s</span><span class="tok-w"> </span><span class="tok-n">nng_tls_engine</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The TLS engine API is provided for developers wishing to implement their +own implementation of TLS, or to adapt a 3rd party TLS implementation to +the work with NNG.</p> +</div> +<div class="paragraph"> +<p>Information about the existing TLS engine can be obtained from the functions +<a href="nng_tls_engine_name.3tls.html"><code>nng_tls_engine_name()</code></a>, +<a href="nng_tls_engine_description.3tls.html"><code>nng_tls_engine_description()</code></a>, and +<a href="nng_tls_engine_fips_mode.3tls.html"><code>nng_tls_engine_fips_mode()</code></a> functions.</p> +</div> +<div class="paragraph"> +<p>At this time, there is no further documentation on implementing a TLS +engine oneself, but existing source code may be a guide. +The primary interfaces are located in the +<code><nng/supplemental/tls/engine.h></code> header file.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_tls_engine_description.3tls.html">nng_tls_engine_description(3tls)</a>, +<a href="nng_tls_engine_fips_mode.3tls.html">nng_tls_engine_fips_mode(3tls)</a>, +<a href="nng_tls_engine_name.3tls.html">nng_tls_engine_name(3tls)</a>, +<a href="nng_tls_config.5.html">nng_tls_config(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_engine_description.3tls.html b/man/v1.7.2/nng_tls_engine_description.3tls.html new file mode 100644 index 00000000..e89b0f8e --- /dev/null +++ b/man/v1.7.2/nng_tls_engine_description.3tls.html @@ -0,0 +1,63 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_engine_description(3tls) +--- +<h1>nng_tls_engine_description(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_engine_description - TLS engine description</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_tls_engine_description</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_engine_description()</code> returns a short description for the current +<a href="nng_tls_engine.5.html">TLS engine</a>. +If no engine is registered, then the empty string ("") is returned. +This is principally useful for diagnostic purposes.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The description of the engine of the engine.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_tls_engine_name.3tls.html">nng_tls_engine_name(3tls)</a>, +<a href="nng_tls_engine.5.html">nng_tls_engine(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_engine_fips_mode.3tls.html b/man/v1.7.2/nng_tls_engine_fips_mode.3tls.html new file mode 100644 index 00000000..560b1d4c --- /dev/null +++ b/man/v1.7.2/nng_tls_engine_fips_mode.3tls.html @@ -0,0 +1,100 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_engine_fips_mode(3tls) +--- +<h1>nng_tls_engine_fips_mode(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_engine_fips_mode - TLS FIPS 140-2 mode indicator</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-kt">bool</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_engine_fips_mode</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_engine_fips_mode()</code> returns <code>true</code> if the +<a href="nng_tls_engine.5.html">TLS engine</a> is operating in FIPS 140-2 mode, +and <code>false</code> otherwise.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +FIPS 140-2 references a United States standard for the use +of cryptography in information processing systems. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The default TLS engine does not support FIPS 140-2 mode, and +will always return false. Alternative implementations with such +support may be available from commercial suppliers. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Generally the FIPS 140-2 mode cannot be changed after program startup. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>True if the TLS engine is in FIPS 140-2 mode, false otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_tls_engine.5.html">nng_tls_engine(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_engine_name.3tls.html b/man/v1.7.2/nng_tls_engine_name.3tls.html new file mode 100644 index 00000000..16b32458 --- /dev/null +++ b/man/v1.7.2/nng_tls_engine_name.3tls.html @@ -0,0 +1,62 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_engine_name(3tls) +--- +<h1>nng_tls_engine_name(3tls)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_engine_name - TLS engine name</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/supplemental/tls/tls.h></span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-nf">nng_tls_engine_name</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_engine_name()</code> returns a short name for the current +<a href="nng_tls_engine.5.html">TLS engine</a>. +If no engine is registered, then the special name "none" is returned.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The name of the engine.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_tls_engine_description.3tls.html">nng_tls_engine_description(3tls)</a>, +<a href="nng_tls_engine.5.html">nng_tls_engine(5)</a> +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_options.5.html b/man/v1.7.2/nng_tls_options.5.html new file mode 100644 index 00000000..378d12be --- /dev/null +++ b/man/v1.7.2/nng_tls_options.5.html @@ -0,0 +1,180 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_options(5) +--- +<h1>nng_tls_options(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_options - TLS-specific options</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-cp">#define NNG_OPT_TLS_AUTH_MODE "tls-authmode"</span> +<span class="tok-cp">#define NNG_OPT_TLS_CA_FILE "tls-ca-file"</span> +<span class="tok-cp">#define NNG_OPT_TLS_CERT_KEY_FILE "tls-cert-key-file"</span> +<span class="tok-cp">#define NNG_OPT_TLS_CONFIG "tls-config"</span> +<span class="tok-cp">#define NNG_OPT_TLS_SERVER_NAME "tls-server-name"</span> +<span class="tok-cp">#define NNG_OPT_TLS_VERIFIED "tls-verified"</span> +<span class="tok-cp">#define NNG_OPT_TLS_PEER_CN "tls-peer-cn"</span> +<span class="tok-cp">#define NNG_OPT_TLS_PEER_ALT_NAMES "tls-peer-alt-names"</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This page documents the various standard options that can be set or +retrieved on objects using TLS.</p> +</div> +<div class="paragraph"> +<p>The option names should always be used by their symbolic definitions.</p> +</div> +<div class="paragraph"> +<p>In the following list of options, the name of the option is supplied, +along with the data type of the underlying value.</p> +</div> +<div class="paragraph"> +<p>Some options are only meaningful or supported in certain contexts, or may +have other access restrictions. +An attempt has been made to include details about such restrictions in the +description of the option.</p> +</div> +<div class="sect2"> +<h3 id="_tls_options">TLS Options</h3> +<div class="dlist"> +<dl> +<dt class="hdlist1"><a id="NNG_OPT_TLS_AUTH_MODE"></a><code>NNG_OPT_TLS_AUTH_MODE</code></dt> +<dd> +<p>(<code>int</code>) +Write-only option used to configure the authentication mode used. +See <a href="nng_tls_config_auth_mode.3tls.html"><code>nng_tls_config_auth_mode()</code></a> for +more details.</p> +</dd> +<dt class="hdlist1"><a id="NNG_OPT_TLS_CA_FILE"></a><code>NNG_OPT_TLS_CA_FILE</code></dt> +<dd> +<p>(string) Write-only option naming a file containing certificates to +use for peer validation. +See <a href="nng_tls_config_ca_file.3tls.html"><code>nng_tls_config_ca_file()</code></a> for more +information.</p> +</dd> +<dt class="hdlist1"><a id="NNG_OPT_TLS_CERT_KEY_FILE"></a><code>NNG_OPT_TLS_CERT_KEY_FILE</code></dt> +<dd> +<p>(string) Write-only option naming a file containing the local certificate and +associated private key. +The private key used must be unencrypted. +See <a href="nng_tls_config_own_cert.3tls.html"><code>nng_tls_config_own_cert()</code></a> for more +information.</p> +</dd> +<dt class="hdlist1"><a id="NNG_OPT_TLS_CONFIG"></a><code>NNG_OPT_TLS_CONFIG</code></dt> +<dd> +<p>(<code>nng_tls_config *</code>) +This option references the underlying +<a href="nng_tls_config.5.html">TLS configuration object</a>. +A hold is placed on the underlying +configuration object before returning it.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The caller should release the hold with +<a href="nng_tls_config_free.3tls.html"><code>nng_tls_config_free()</code></a> when it no +longer needs the TLS configuration object. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Use this option when more advanced TLS configuration is required. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><a id="NNG_OPT_TLS_SERVER_NAME"></a><code>NNG_OPT_TLS_SERVER_NAME</code></dt> +<dd> +<p>(string) +This write-only option is used to specify the name of the server. +When used with a dialer, this potentially configures SNI (server name +indication, which is used as a hint by a multihosting server to choose the +appropriate certificate to provide) and also is used to validate the +name presented in the server’s x509 certificate.</p> +</dd> +<dt class="hdlist1"><a id="NNG_OPT_TLS_VERIFIED"></a><code>NNG_OPT_TLS_VERIFIED</code></dt> +<dd> +<p>(<code>bool</code>) +This read-only option indicates whether the remote peer has been properly verified using TLS +authentication. +May return incorrect results if peer authentication is disabled.</p> +</dd> +<dt class="hdlist1"><a id="NNG_OPT_TLS_PEER_CN"></a><code>NNG_OPT_TLS_PEER_CN</code></dt> +<dd> +<p>(string) +This read-only option returns the common name of the peer certificate. +May return incorrect results if peer authentication is disabled.</p> +</dd> +<dt class="hdlist1"><a id="NNG_OPT_TLS_PEER_ALT_NAMES"></a><code>NNG_OPT_TLS_PEER_ALT_NAMES</code></dt> +<dd> +<p>(string) +This read-only option returns string list with the subject alternative names of the +peer certificate. May return incorrect results if peer authentication is disabled.</p> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_inherited_options">Inherited Options</h3> +<div class="paragraph"> +<p>Generally, the following option values are also available for TLS objects, +when appropriate for the context:</p> +</div> +<div class="ulist"> +<ul> +<li> +<p><a href="nng_options.5.html#NNG_OPT_LOCADDR"><code>NNG_OPT_LOCADDR</code></a></p> +</li> +<li> +<p><a href="nng_options.5.html#NNG_OPT_REMADDR"><code>NNG_OPT_REMADDR</code></a></p> +</li> +<li> +<p><a href="nng_tcp_options.5.html#NNG_OPT_TCP_KEEPALIVE"><code>NNG_OPT_TCP_KEEPALIVE</code></a></p> +</li> +<li> +<p><a href="nng_tcp_options.5.html#NNG_OPT_TCP_NODELAY"><code>NNG_OPT_TCP_NODELAY</code></a></p> +</li> +</ul> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_options.5.html">nng_options(5)</a> +<a href="nng_tcp_options.5.html">nng_tcp_options(5)</a> +<a href="nng_tls_config.5.html">nng_tls_config(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_tls_register.3.html b/man/v1.7.2/nng_tls_register.3.html new file mode 100644 index 00000000..9efcdde4 --- /dev/null +++ b/man/v1.7.2/nng_tls_register.3.html @@ -0,0 +1,77 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_tls_register(3) +--- +<h1>nng_tls_register(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_tls_register - register tls transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/tls/tls.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_tls_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_tls_register()</code> function registers the +<em>tls</em> transport for use.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The transport is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_tls.7.html">nng_tls(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_url.5.html b/man/v1.7.2/nng_url.5.html new file mode 100644 index 00000000..6f843b76 --- /dev/null +++ b/man/v1.7.2/nng_url.5.html @@ -0,0 +1,176 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_url(5) +--- +<h1>nng_url(5)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_url - Universal Resource Locator object</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">typedef</span><span class="tok-w"> </span><span class="tok-k">struct</span><span class="tok-w"> </span><span class="tok-nc">nng_url</span><span class="tok-w"> </span><span class="tok-p">{</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u_rawurl</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u_scheme</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u_userinfo</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u_host</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u_hostname</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u_port</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u_path</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u_query</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u_fragment</span><span class="tok-p">;</span> +<span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">u_requri</span><span class="tok-p">;</span> +<span class="tok-p">}</span><span class="tok-w"> </span><span class="tok-n">nng_url</span><span class="tok-p">;</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +An <code>nng_url</code> is a structure used for +representing URLs. +These structures are created by parsing string formatted URLs with +<a href="nng_url_parse.3.html"><code>nng_url_parse()</code></a>.</p> +</div> +<div class="paragraph"> +<p>Applications may access individual fields, but must not free or +alter them, as the underlying memory is managed by the library.</p> +</div> +<div class="paragraph"> +<p>The fields are as follows:</p> +</div> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>u_rawurl</code> +</td> +<td class="hdlist2"> +<p>The unparsed URL string. This will never be <code>NULL</code>.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>u_scheme</code> +</td> +<td class="hdlist2"> +<p>The URL scheme, such as "http" or "inproc". Always lower case. This will never be <code>NULL</code>.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>u_userinfo</code> +</td> +<td class="hdlist2"> +<p>This username and password if supplied in the URL string. Will be <code>NULL</code> when not present.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>u_host</code> +</td> +<td class="hdlist2"> +<p>The full host part of the URL, including the port if present (separated by a colon.)</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>u_hostname</code> +</td> +<td class="hdlist2"> +<p>The name of the host, and may be the empty string in some cases.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>u_port</code> +</td> +<td class="hdlist2"> +<p>The port. May be empty if irrelevant or not specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>u_path</code> +</td> +<td class="hdlist2"> +<p>The path, typically used with HTTP or WebSockets. Will be empty string if not specified.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>u_query</code> +</td> +<td class="hdlist2"> +<p>The query info (typically following <code>?</code> in the URL.) Will be <code>NULL</code> if not present.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>u_fragment</code> +</td> +<td class="hdlist2"> +<p>This is used for specifying an anchor, the part after <code>#</code> in a URL. Will be <code>NULL</code> if not present.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>u_requri</code> +</td> +<td class="hdlist2"> +<p>The full Request-URI (path[?query][#fragment]). Will be the empty string if not specified.</p> +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Other fields may also be present, but only those documented here are safe for application use. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +More information about Universal Resource Locators can be found in +<a href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_url_clone.3.html">nng_url_clone(3)</a>, +<a href="nng_url_free.3.html">nng_url_free(3)</a>, +<a href="nng_url_parse.3.html">nng_url_parse(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_url_clone.3.html b/man/v1.7.2/nng_url_clone.3.html new file mode 100644 index 00000000..91853092 --- /dev/null +++ b/man/v1.7.2/nng_url_clone.3.html @@ -0,0 +1,79 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_url_clone(3) +--- +<h1>nng_url_clone(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_url_clone - clone URL structure</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_url_clone</span><span class="tok-p">(</span><span class="tok-n">nng_url</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">dup</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-n">nng_url</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">orig</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_url_clone()</code> makes a clone of the original URL structure <em>orig</em>, and +saves the result in the location pointed by <em>dup</em>. +This clone includes fully duplicating each of the member fields.</p> +</div> +<div class="paragraph"> +<p>The new +<a href="nng_url.5.html"><code>nng_url</code></a> structure can be disposed of +using +<a href="nng_url_free.3.html"><code>nng_url_free()</code></a> when it is no longer needed.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists to duplicate a message.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_url_free.3.html">nng_url_free(3)</a>, +<a href="nng_url_parse.3.html">nng_url_parse(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_url.5.html">nng_url(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_url_free.3.html b/man/v1.7.2/nng_url_free.3.html new file mode 100644 index 00000000..6e17777c --- /dev/null +++ b/man/v1.7.2/nng_url_free.3.html @@ -0,0 +1,62 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_url_free(3) +--- +<h1>nng_url_free(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_url_free - free a URL structure</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">void</span><span class="tok-w"> </span><span class="tok-nf">nng_url_free</span><span class="tok-p">(</span><span class="tok-n">nng_url</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">url</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_url_free()</code> function deallocates the <em>url</em> entirely, including +any of its members.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_url_clone.3.html">nng_url_clone(3)</a>, +<a href="nng_url_parse.3.html">nng_url_parse(3)</a>, +<a href="nng_url.5.html">nng_url(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_url_parse.3.html b/man/v1.7.2/nng_url_parse.3.html new file mode 100644 index 00000000..e8fc0db7 --- /dev/null +++ b/man/v1.7.2/nng_url_parse.3.html @@ -0,0 +1,146 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_url_parse(3) +--- +<h1>nng_url_parse(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_url_parse - create URL structure from a string</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_url_parse</span><span class="tok-p">(</span><span class="tok-n">nng_url</span><span class="tok-w"> </span><span class="tok-o">**</span><span class="tok-n">urlp</span><span class="tok-p">,</span><span class="tok-w"> </span><span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-n">str</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_url_parse()</code> function parses the string <em>str</em> containing an +<a href="https://tools.ietf.org/html/rfc3986">RFC 3986</a> compliant URL, and creates +an +<a href="nng_url.5.html"><code>nng_url</code></a> structure containing the results. +A pointer to the resulting structure is stored in <em>urlp</em>.</p> +</div> +<div class="paragraph"> +<p>The structure may disposed of when no longer needed by calling +<a href="nng_url_free.3.html"><code>nng_url_free()</code></a>.</p> +</div> +<div class="sect2"> +<h3 id="_url_canonicalization">URL Canonicalization</h3> +<div class="paragraph"> +<p>The <code>nng_url_parse()</code> function also canonicalizes the results, as +follows:</p> +</div> +<div class="olist arabic"> +<ol class="arabic"> +<li> +<p>The URL is parsed into the various components.</p> +</li> +<li> +<p>The <code>u_scheme</code>, <code>u_hostname</code>, <code>u_host</code>, and <code>u_port</code> members are +converted to lower case.</p> +</li> +<li> +<p>Percent-encoded values for +<a href="https://tools.ietf.org/html/rfc3986#section-2.3">unreserved characters</a> +converted to their unencoded forms.</p> +</li> +<li> +<p>Additionally URL percent-encoded values for characters in the path +and with numeric values larger than 127 (i.e. not ASCII) are decoded.</p> +</li> +<li> +<p>The resulting <code>u_path</code> 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, and +the function returns <code>NNG_EINVAL</code>.</p> +</li> +<li> +<p>Path segments consisting of <code>.</code> and <code>..</code> are resolved as per +<a href="https://tools.ietf.org/html/rfc3986#section-6.2.2.3">RFC 3986 6.2.2.3</a>.</p> +</li> +<li> +<p>Further, empty path segments are removed, meaning that duplicate +slash (<code>/</code>) separators are removed from the path.</p> +</li> +<li> +<p>If a port was not specified, but the scheme defines a default +port, then <code>u_port</code> will be filled in with the value of the default port.</p> +</li> +</ol> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Only the <code>u_userinfo</code>, <code>u_query</code>, and <code>u_fragment</code> members will ever be + <code>NULL</code>. The other members will be filled in with either default values + or the empty string if they cannot be determined from <em>str</em>. +</td> +</tr> +</table> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient free memory exists to allocate a message.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_EINVAL</code> +</td> +<td class="hdlist2"> +<p>An invalid URL was supplied.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_url_clone.3.html">nng_url_clone(3)</a>, +<a href="nng_url_free.3.html">nng_url_free(3)</a>, +<a href="nng_strerror.3.html">nng_strerror(3)</a>, +<a href="nng_url.5.html">nng_url(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_version.3.html b/man/v1.7.2/nng_version.3.html new file mode 100644 index 00000000..4a5f9111 --- /dev/null +++ b/man/v1.7.2/nng_version.3.html @@ -0,0 +1,101 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_version(3) +--- +<h1>nng_version(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_version - report library version</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/nng.h></span> + +<span class="tok-k">const</span><span class="tok-w"> </span><span class="tok-kt">char</span><span class="tok-w"> </span><span class="tok-o">*</span><span class="tok-w"> </span><span class="tok-nf">nng_version</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_version()</code> function returns a human readable version number +for <em>NNG</em>.</p> +</div> +<div class="paragraph"> +<p>Additionally, compile time version information is available +via some predefined macros:</p> +</div> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_MAJOR_VERSION</code> +</td> +<td class="hdlist2"> +<p>Major version number.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_MINOR_VERSION</code> +</td> +<td class="hdlist2"> +<p>Minor version number.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_PATCH_VERSION</code> +</td> +<td class="hdlist2"> +<p>Patch version number.</p> +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p><em>NNG</em> is developed and released using +<a href="http://www.semver.org">Semantic Versioning 2.0</a>, and +the version numbers reported refer to both the API and the +library itself. +(The ABI — application binary interface — between the +library and the application is controlled in a similar, but different +manner depending upon the link options and how the library is built.)</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>Null-terminated string containing the library version number.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>None.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ws.7.html b/man/v1.7.2/nng_ws.7.html new file mode 100644 index 00000000..f725b000 --- /dev/null +++ b/man/v1.7.2/nng_ws.7.html @@ -0,0 +1,360 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ws(7) +--- +<h1>nng_ws(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ws - WebSocket transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/websocket/ws.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ws_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span> +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_wss_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>ws</em> transport provides communication support between +peers across a TCP/IP network using +<a href="https://tools.ietf.org/html/rfc6455">WebSockets</a>. +Both IPv4 and IPv6 are supported when the underlying platform also supports it.</p> +</div> +<div class="paragraph"> +<p>The protocol details are documented in +<a href="http://nanomsg.org/rfcs/sp-websocket-v1.html">WebSocket Mapping for Scalability Protocols</a>.</p> +</div> +<div class="sect2"> +<h3 id="_registration">Registration</h3> +<div class="paragraph"> +<p>Depending upon how the library was built, it may be necessary to +register the transport by calling <a href="nng_ws_register.3.html"><code>nng_ws_register()</code></a>.</p> +</div> +<div class="paragraph"> +<p>If TLS support is enabled in the library, secure WebSockets (over TLS v1.2) +can be used as well, but the secure transport may have to be registered using +the <a href="nng_wss_register.3.html"><code>nng_wss_register()</code></a> function.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_uri_format">URI Format</h3> +<div class="paragraph"> +<p> +This transport uses URIs using the scheme <code>ws://</code>, followed by +an IP address or hostname, optionally followed by a colon and an +TCP port number, optionally followed by a path. +(If no port number is specified then port 80 is assumed. +If no path is specified then a path of <code>/</code> is assumed.) +For example, the URI <code>ws://localhost/app/pubsub</code> would use +port 80 on localhost, with the path <code>/app/pubsub</code>.</p> +</div> +<div class="paragraph"> +<p>Secure WebSockets +(if enabled) use the scheme <code>wss://</code>, and the default TCP port number of 443. +Otherwise the format is the same as for regular WebSockets.</p> +</div> +<div class="paragraph"> +<p>A URI may be restricted to IPv6 using the scheme <code>ws6://</code> or <code>wss6://</code>, and may +be restricted to IPv4 using the scheme <code>ws4://</code> or <code>wss4://</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +Specifying <code>ws6://</code> or <code>wss6://</code> may not prevent IPv4 hosts from being used with +IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with +listeners. +The details of this varies across operating systems. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The <code>ws4://</code> , <code>ws6://</code>, <code>wss4://</code> and <code>wss6://</code> schemes are specific to <em>NNG</em>, +and might not be understood by other implementations. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +We recommend using either numeric IP addresses, or names that are +specific to either IPv4 or IPv6 to prevent confusion and surprises. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>When specifying IPv6 addresses, the address must be enclosed in +square brackets (<code>[]</code>) to avoid confusion with the final colon +separating the port.</p> +</div> +<div class="paragraph"> +<p>For example, the same path and port on the IPv6 loopback address (<code>::1</code>) +would be specified as <code>ws://[::1]/app/pubsub</code>.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The value specified as the host, if any, will also be used +in the <code>Host:</code> HTTP header during HTTP negotiation. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>To listen to all ports on the system, the host name may be elided from +the URL on the listener. This will wind up listening to all interfaces +on the system, with possible caveats for IPv4 and IPv6 depending on what +the underlying system supports. (On most modern systems it will map to the +special IPv6 address <code>::</code>, and both IPv4 and IPv6 connections will be +permitted, with IPv4 addresses mapped to IPv6 addresses.)</p> +</div> +</div> +<div class="sect2"> +<h3 id="_socket_address">Socket Address</h3> +<div class="paragraph"> +<p>When using an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> structure, +the actual structure is either of type +<a href="nng_sockaddr_in.5.html"><code>nng_sockaddr_in</code></a> (for IPv4) or +<a href="nng_sockaddr_in6.5.html"><code>nng_sockaddr_in6</code></a> (for IPv6).</p> +</div> +</div> +<div class="sect2"> +<h3 id="_server_instances">Server Instances</h3> +<div class="paragraph"> +<p>This transport makes use of shared HTTP server +instances, permitting multiple +sockets or listeners to be configured with the same hostname and port. +When creating a new listener, it is registered with an existing HTTP server +instance if one can be found. +Note that the matching algorithm is somewhat simple, +using only a string based hostname or IP address and port to match. +Therefore it is recommended to use only IP addresses or the empty string as +the hostname in listener URLs.</p> +</div> +<div class="paragraph"> +<p>Likewise, when sharing a server instance, it may not be possible to alter +TLS configuration if the server is already running, as there is only a single +TLS configuration context for the entire server instance.</p> +</div> +<div class="paragraph"> +<p>All sharing of server instances is only typically possible within the same +process.</p> +</div> +<div class="paragraph"> +<p>The server may also be used by other things (for example to serve static +content), in the same process.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_transport_options">Transport Options</h3> +<div class="paragraph"> +<p>The following transport options are available. Note that +setting these must be done before the transport is started.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The TLS specific options (beginning with <code>NNG_OPT_TLS_</code>) are +only available for <code>wss://</code> endpoints. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_WS_REQUEST_HEADERS</code></dt> +<dd> +<p>(string) Concatenation of multiple lines terminated +by CRLF sequences, that can be used to add further headers to the +HTTP request sent when connecting. +This option can be set on dialers, and retrieved from pipes.</p> +</dd> +<dt class="hdlist1"><code>NNG_OPT_WS_RESPONSE_HEADERS</code></dt> +<dd> +<p>(string) Concatenation of multiple lines terminated +by CRLF sequences, that can be used to add further headers to the +HTTP response sent when connecting. +This option can be set on listeners, and retrieved from pipes.</p> +</dd> +<dt class="hdlist1"><code>NNG_OPT_WS_RECV_TEXT</code></dt> +<dd> +<p>(bool) Enable receiving of TEXT frames at the WebSocket layer. +This option should only be used with the low level +<a href="nng_stream.5.html"><code>nng_stream</code></a> API. +When set, the stream will accept in-bound TEXT frames as well as BINARY frames.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +The SP protocols (such as <a href="nng_req.7.html">REQ</a>) require BINARY frames as they pass binary protocol data. +Hence this option should not be used with such protocols. +</td> +</tr> +</table> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +RFC 6455 requires that TEXT frames be discarded and the connection closed if the frame does not contain valid UTF-8 data. +NNG does not perform any such validation. +Applications that need to be strictly conformant should check for this themselves. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_WS_SEND_TEXT</code></dt> +<dd> +<p>(bool) Enable sending of TEXT frames at the WebSocket layer. +This option should only be used with the low level +<a href="nng_stream.5.html"><code>nng_stream</code></a> API. +When set, the stream will send TEXT frames instead of BINARY frames.</p> +</dd> +</dl> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +NNG does not check the frame data, and will attempt to send whatever the client requests. +Peers that are compliant with RFC 6455 will discard TEXT frames (and break the connection) if they do not contain valid UTF-8. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_TLS_CONFIG</code></dt> +<dd> +<p>(<code>nng_tls_config *</code>) The underlying TLS +configuration object for <code>wss://</code> endpoints. +A hold is placed on the underlying +configuration object before returning it. +The caller should release the object with +<a href="nng_tls_config_free.3tls.html"><code>nng_tls_config_free()</code></a> when it no +longer needs the TLS configuration.</p> +</dd> +</dl> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +Use this option when advanced TLS configuration is required. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_TLS_CA_FILE</code></dt> +<dd> +<p>(string) Write-only option naming a file containing certificates to +use for peer validation. +See <a href="nng_tls_config_ca_file.3tls.html"><code>nng_tls_config_ca_file()</code></a> for more +information.</p> +</dd> +<dt class="hdlist1"><code>NNG_OPT_TLS_CERT_KEY_FILE</code></dt> +<dd> +<p>(string) Write-only option naming a file containing the local certificate and +associated private key. +The private key used must be unencrypted. +See <a href="nng_tls_config_own_cert.3tls.html"><code>nng_tls_config_own_cert()</code></a> for more +information.</p> +</dd> +<dt class="hdlist1"><code>NNG_OPT_TLS_AUTH_MODE</code></dt> +<dd> +<p>(<code>int</code>) Write-only option used to configure the authentication mode used. +See <a href="nng_tls_config_auth_mode.3tls.html"><code>nng_tls_config_auth_mode()</code></a> for +more details.</p> +</dd> +<dt class="hdlist1"><code>NNG_OPT_TLS_VERIFIED</code></dt> +<dd> +<p>(<code>bool</code>) Whether the remote peer has been properly verified using TLS +authentication. +May return incorrect results if peer authentication is disabled.</p> +</dd> +<dt class="hdlist1"><code>NNG_OPT_TLS_PEER_CN</code></dt> +<dd> +<p>(string) This read-only option returns the common name of the peer certificate. +May return incorrect results if peer authentication is disabled.</p> +</dd> +<dt class="hdlist1"><code>NNG_OPT_TLS_PEER_ALT_NAMES</code></dt> +<dd> +<p>(string list) returns string list with the subject alternative names of the +peer certificate. May return incorrect results if peer authentication +is disabled.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_tls_config_alloc.3tls.html">nng_tls_config_alloc(3tls)</a>, +<a href="nng_sockaddr.5.html">nng_sockaddr(5)</a>, +<a href="nng_sockaddr_in.5.html">nng_sockaddr_in(5)</a>, +<a href="nng_sockaddr_in6.5.html">nng_sockaddr_in6(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_ws_register.3.html b/man/v1.7.2/nng_ws_register.3.html new file mode 100644 index 00000000..29e35c2f --- /dev/null +++ b/man/v1.7.2/nng_ws_register.3.html @@ -0,0 +1,90 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_ws_register(3) +--- +<h1>nng_ws_register(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_ws_register - register WebSocket transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/websocket/ws.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_ws_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_ws_register()</code> function registers the +<em>ws</em> transport for use.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The transport is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_ws.7.html">nng_ws(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_wss_register.3.html b/man/v1.7.2/nng_wss_register.3.html new file mode 100644 index 00000000..75d70e41 --- /dev/null +++ b/man/v1.7.2/nng_wss_register.3.html @@ -0,0 +1,90 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_wss_register(3) +--- +<h1>nng_wss_register(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_wss_register - register WebSocket secure transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/websocket/ws.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_wss_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_wss_register()</code> function registers the +<em>wss</em> transport for use.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The transport is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_ws.7.html">nng_ws(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_zerotier.7.html b/man/v1.7.2/nng_zerotier.7.html new file mode 100644 index 00000000..8bc1aad3 --- /dev/null +++ b/man/v1.7.2/nng_zerotier.7.html @@ -0,0 +1,359 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_zerotier(7) +--- +<h1>nng_zerotier(7)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_zerotier - ZeroTier transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/zerotier/zerotier.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_zt_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p> +The <em>zt</em> transport provides communication support for +<em>NNG</em> applications over a <a href="http://www.zerotier.com">ZeroTier</a> network, +using a Virtual Layer 2 packet facility.</p> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +This transport is experimental. +To utilize it at present, the library must be built with support, and linked +against a suitable <code>libzerotiercore</code> library. +Further information about building with this support are in the build +documentation included with the distribution. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +The <code>libzerotiercore</code> library at present is covered under different +license terms than the rest of <em>NNG</em>. Please be careful to review +and adhere to the licensing terms. +</td> +</tr> +</table> +</div> +<div class="admonitionblock important"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-important" title="Important"></i> +</td> +<td class="content"> +The ZeroTier transport can take a long time to establish an +initial connection — up to even a minute in extreme cases, while the network +topology is configured. Consequently, this transport is not recommended +for use cases involving short-lived programs, but is better for long-running +programs such as background daemons or agents. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>While ZeroTier makes use of the host’s IP stack (and UDP in particular), +this transport does not use or require an IP stack on the virtual +network; thereby mitigating any considerations about IP address management.</p> +</div> +<div class="paragraph"> +<p>This service uses Ethernet type 901 to transport packets. Network rules +must permit this Ethernet type to pass in order to have a functional +network.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This document assumes that the reader is familiar with ZeroTier +concepts and administration. +</td> +</tr> +</table> +</div> +<div class="sect2"> +<h3 id="_registration">Registration</h3> +<div class="paragraph"> +<p>Depending upon how the library was built, it may be necessary to +register the transport by calling +<a href="nng_zt_register.3.html"><code>nng_zt_register()</code></a>. +This function +returns zero on success, or an nng error value if the transport +cannot be initialized for any reason.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_uri_format">URI Format</h3> +<div class="paragraph"> +<p> +This transport uses URIs using the scheme <code>zt://</code>, followed by a node +number (ten hexadecimal digits) followed by a <code>.</code> delimited, and then +a network address (sixteen hexadecimal digits), followed by a colon (<code>:</code>) +and service or port number (decimal value, +up to 24-bits). +For example, the URI <code>zt://fedcba9876.0123456789abdef:999</code> indicates +that node fedcba9876 on network 0123456789abcdef is listening on port 999.</p> +</div> +<div class="paragraph"> +<p>The special value <code>*</code> can be used in lieu of a node number to represent +the node’s own node number.</p> +</div> +<div class="paragraph"> +<p>Listeners may use port 0 to indicate that a suitable port +number be selected automatically. +Applications using this must determine the selected port number using the +<a href="nng_listener_getopt.3.html"><code>nng_listener_getopt()</code></a> function.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_socket_address">Socket Address</h3> +<div class="paragraph"> +<p>When using an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> structure, +the actual structure is of type +<a href="nng_sockaddr_zt.5.html"><code>nng_sockaddr_zt</code></a>.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_node_presence">Node Presence</h3> +<div class="paragraph"> +<p>By default this transport creates an "ephemeral" node, and used the +same ephemeral node for any additional endpoints created. +As this node is ephemeral, the keys associated with it and all associated data +are located in memory and are discarded upon application termination. +If a persistent node is desired, please see the <code>NNG_OPT_ZT_HOME</code> option.</p> +</div> +<div class="paragraph"> +<p>It is possible for a single application to join multiple networks +using the same node, or using separate nodes.</p> +</div> +</div> +<div class="sect2"> +<h3 id="_network_status">Network Status</h3> +<div class="paragraph"> +<p> +A ZeroTier node can be in one of the following states, which can be obtained +with the <code>NNG_OPT_ZT_NETWORK_STATUS</code> option:</p> +</div> +<div id="NNG_ZT_STATUS_UP" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_ZT_STATUS_UP</code></dt> +<dd> +<p>The ZeroTier network is up. +This is the only state where it is possible to communicate with peers, +and the only state where the network name (<code>NNG_OPT_ZT_NETWORK_NAME</code>) +is available.</p> +</dd> +<dt class="hdlist1"><code>NNG_ZT_STATUS_CONFIG</code></dt> +<dd> +<p>The ZeroTier node is still configuring, network services are not available.</p> +</dd> +<dt class="hdlist1"><code>NNG_ZT_STATUS_DENIED</code></dt> +<dd> +<p>The node does not have permission to join the ZeroTier network.</p> +</dd> +<dt class="hdlist1"><code>NNG_ZT_STATUS_NOTFOUND</code></dt> +<dd> +<p>The ZeroTier network is not found.</p> +</dd> +<dt class="hdlist1"><code>NNG_ZT_STATUS_ERROR</code></dt> +<dd> +<p>Some other ZeroTier error has occurred; the network is not available.</p> +</dd> +<dt class="hdlist1"><code>NNG_ZT_STATUS_OBSOLETE</code></dt> +<dd> +<p>The node is running obsolete software; the network is not available.</p> +</dd> +<dt class="hdlist1"><code>NNG_ZT_STATUS_UNKNOWN</code></dt> +<dd> +<p>The network is in an unknown state. This should not happen, as it +indicates that the ZeroTier software is reporting an unexpected status. +The network is most likely not available.</p> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_transport_options">Transport Options</h3> +<div class="paragraph"> +<p>The following transport options are available:</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_ZT_HOME</code></dt> +<dd> +<p>(string) This option represents the home directory, where the transport +can store (and reuse) persistent state, such as key materials, node +identity, and federation membership. +This option must be set before the ZeroTier transport is first used. +If this value is empty, then an ephemeral ZeroTier node is created, +and no persistent state is used. +The default is to use an ephemeral node.</p> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +If this option is set to different values on different sockets, +dialers, or listeners, then separate nodes will be created. +It is perfectly valid for an application to have multiple node identities +in this fashion. +</td> +</tr> +</table> +</div> +</dd> +<dt class="hdlist1"><code>NNG_OPT_ZT_NWID</code></dt> +<dd> +<p>(<code>uint64_t</code>) The 64-bit ZeroTier network number (native byte order).</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_ZT_NODE" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_ZT_NODE</code></dt> +<dd> +<p>(<code>uint64_t</code>) The ZeroTier 40-bit node address (native byte order).</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_ZT_NETWORK_STATUS" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_ZT_NETWORK_STATUS</code></dt> +<dd> +<p> +(<code>int</code>) The ZeroTier network status. +See <a href="#_network_status">Network Status</a> for an explanation of this option.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_ZT_NETWORK_NAME" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_ZT_NETWORK_NAME</code></dt> +<dd> +<p> +(string) The name of the network +as established by the ZeroTier network administrator.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_ZT_CONN_TIME" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_ZT_CONN_TIME</code></dt> +<dd> +<p>(<a href="nng_duration.5.html"><code>nng_duration</code></a>) +The time to wait between sending connection attempts, +only used with dialers. +The default is 500 msec.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_ZT_CONN_TRIES" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_ZT_CONN_TRIES</code></dt> +<dd> +<p>(<code>int</code>) The maximum number of attempts to try to establish a connection +before reporting a timeout, and is only used with dialers. +The default is 240, which results in a 2 minute timeout if +<code>NNG_OPT_ZT_CONN_TIME</code> is at its default of 500. +If the value is set to 0, then connection attempts will keep retrying forever.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_ZT_PING_TIME" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_ZT_PING_TIME</code></dt> +<dd> +<p>(<a href="nng_duration.5.html"><code>nng_duration</code></a>) If no traffic has been received from +the ZeroTier peer after this +period of time, then a ping message is sent to check if the peer +is still alive.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_ZT_PING_TRIES" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_ZT_PING_TRIES</code></dt> +<dd> +<p>(<code>int</code>) If this number of consecutive ping requests are sent to the +peer with no response (and no other intervening traffic), then the +peer is assumed to be dead and the connection is closed.</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_ZT_MTU" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_ZT_MTU</code></dt> +<dd> +<p>(<code>size_t</code>) The ZeroTier virtual network MTU (read-only) as configured +on the network; this is the Virtual Layer 2 MTU. The headers used by +this transport and the protocols consume some of this for each message +sent over the network. (The transport uses 20-bytes of this, and each +protocol may consume additional space, typically not more than 16-bytes.)</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_ZT_ORBIT" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_ZT_ORBIT</code></dt> +<dd> +<p>(<code>uint64_t[2]</code>) Write-only array of two <code>uint64_t</code> values, +indicating the ID of a ZeroTier <em>moon</em>, and the node ID of the root server +for that moon. (The ID may be zero if the moon ID is the same as its +root server ID, which is conventional.)</p> +</dd> +</dl> +</div> +<div id="NNG_OPT_ZT_DEORBIT" class="dlist"> +<dl> +<dt class="hdlist1"><code>NNG_OPT_ZT_DEORBIT</code></dt> +<dd> +<p>(<code>uint64_t</code>) Write-only option indicating the moon ID to deorbit. +If the node is not already orbiting the moon, then this has no effect.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_sockaddr_zt.5.html">nng_sockaddr_zt(5)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nng_zt_register.3.html b/man/v1.7.2/nng_zt_register.3.html new file mode 100644 index 00000000..aa49053a --- /dev/null +++ b/man/v1.7.2/nng_zt_register.3.html @@ -0,0 +1,90 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nng_zt_register(3) +--- +<h1>nng_zt_register(3)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nng_zt_register - register ZeroTier transport</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf"><nng/transport/zerotier/zerotier.h></span> + +<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_zt_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <code>nng_zt_register()</code> function registers the +<em>zt</em> transport for use.</p> +</div> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_values">RETURN VALUES</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>This function returns 0 on success, and non-zero otherwise.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_errors">ERRORS</h2> +<div class="sectionbody"> +<div class="hdlist"> +<table> +<tr> +<td class="hdlist1"> +<code>NNG_ENOMEM</code> +</td> +<td class="hdlist2"> +<p>Insufficient memory is available.</p> +</td> +</tr> +<tr> +<td class="hdlist1"> +<code>NNG_ENOTSUP</code> +</td> +<td class="hdlist2"> +<p>The transport is not supported.</p> +</td> +</tr> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="nng_zerotier.7.html">nng_zerotier(7)</a>, +<a href="nng.7.html">nng(7)</a></p> +</div> +</div> +</div> diff --git a/man/v1.7.2/nngcat.1.html b/man/v1.7.2/nngcat.1.html new file mode 100644 index 00000000..b4d5a619 --- /dev/null +++ b/man/v1.7.2/nngcat.1.html @@ -0,0 +1,492 @@ +--- +version: v1.7.2 +layout: manpage_v2 +title: nngcat(1) +--- +<h1>nngcat(1)</h1> +<div class="sect1"> +<h2 id="_name">NAME</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>nngcat - command line access to Scalability Protocols</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_synopsis">SYNOPSIS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p><strong>nngcat</strong> --help</p> +</div> +<div class="paragraph"> +<p><strong>nngcat</strong> --version</p> +</div> +<div class="paragraph"> +<p><strong>nngcat</strong> [<em>OPTION</em>]…​</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">DESCRIPTION</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The <em>nngcat</em> utility provides command line access to the Scalability +Protocols, making it possible to write shell scripts that interact +with other peers in a Scalability Protocols topology, by both sending and +receiving messages.</p> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_options">OPTIONS</h2> +<div class="sectionbody"> +<div class="paragraph"> +<p>The possible values for <em>OPTION</em> are described below.</p> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +The <em>nngcat</em> utility accepts shortened versions of these options, as long +as the supplied option is unambiguous. +For example <code>--comp</code> can be used in lieu +of <code>--compat</code>, but <code>--re</code> may not be used for anything because it could mean +any of <code>--req</code>, <code>--rep</code>, or <code>--respondent</code>. +</td> +</tr> +</table> +</div> +<div class="paragraph"> +<p>When using the long form of an option (names prefixed with with <code>--</code>), if the +option takes a value then the value may be supplied by appending the option +with an equals sign and the value (e.g. <code>--subscribe=times</code>), by appending +the option with a colon and the value (e.g. <code>--subscribe:tribune</code>) or by +providing the data as the next program argument (e.g. <code>--subscribe herald</code>).</p> +</div> +<div class="paragraph"> +<p>When using short form options (a single letter prefixed with a <code>-</code>), +if the option takes a value it may either be immediately appended to +the value (e.g. <code>-L5678</code>) or provided as the next program argument +(e.g. <code>-L 5678</code>).</p> +</div> +<div class="paragraph"> +<p>POSIX style option clustering of single letter options is not supported; +each option must be presented as a separate argument to the program.</p> +</div> +<div class="sect2"> +<h3 id="_generic_options">Generic Options</h3> +<div class="dlist"> +<dl> +<dt class="hdlist1"><strong>-h, --help</strong></dt> +<dd> +<p>Get usage help.</p> +</dd> +<dt class="hdlist1"><strong>-V, --version</strong></dt> +<dd> +<p>Print the version and exit.</p> +</dd> +<dt class="hdlist1"><strong>-v, --verbose</strong></dt> +<dd> +<p>Select verbose operation.</p> +</dd> +<dt class="hdlist1"><strong>-q, --silent</strong></dt> +<dd> +<p>Select silent operation.</p> +</dd> +<dt class="hdlist1"><strong>--compat</strong></dt> +<dd> +<p>Compatible mode. +This cause <em>nngcat</em> to behave more like the legacy +<em>nanocat</em> application. +In this mode connections are made asynchronously, +and the <strong>--pair</strong> option selects version 0 of +the <a href="nng_pair.7.html"><em>pair</em></a> protocol instead of version 1.</p> +</dd> +<dt class="hdlist1"><strong>--subscribe</strong>=<em>TOPIC</em></dt> +<dd> +<p>Subscribe to <em>TOPIC</em>. This option can only be used with the +<a href="nng_sub.7.html"><em>sub</em></a> protocol. +The <em>TOPIC</em> is checked against the first bytes +of messages received, and messages are discarded if they do not match. +This may be specified multiple times to subscribe to multiple topics. +If not specified at all, then a default subscription to everything is assumed.</p> +</dd> +<dt class="hdlist1"><strong>--count=</strong>=<em>COUNT</em></dt> +<dd> +<p>Limit the number of iterations when looping to <em>COUNT</em> iterations. +For protocols that only send, this will only send <em>COUNT</em> messages before +exiting. +For protocols that only receive, this will only receive <em>COUNT</em> messages +before exiting. +For protocols that involve a full exchange, this will only perform <em>COUNT</em> +exchanges (each exchange is characterized by at most a single send, and +one or more receives.) +If <em>COUNT</em> is zero, then an infinite number of iterations is performed.</p> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_protocol_selection_options">Protocol Selection Options</h3> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +At least one protocol must be selected. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><strong>--bus, --bus0</strong></dt> +<dd> +<p>Select the <a href="nng_bus.7.html"><em>bus</em></a> version 0 protocol. +This protocol can send and receive messages to and from other <em>bus</em> version 0 +peers.</p> +</dd> +<dt class="hdlist1"><strong>--req, --req0</strong></dt> +<dd> +<p>Select the <a href="nng_req.7.html"><em>req</em></a> version 0 protocol. +This protocol sends messages to <a href="nng_rep.7.html"><em>rep</em></a> version 0 +peers and receives replies from them.</p> +</dd> +<dt class="hdlist1"><strong>--rep, --rep0</strong></dt> +<dd> +<p>Select the <a href="nng_rep.7.html"><em>rep</em></a> version 0 protocol. +This protocol receives messages from <a href="nng_req.7.html"><em>req</em></a> version 0 peers +and can send replies to them.</p> +</dd> +<dt class="hdlist1"><strong>--pub, --pub0</strong></dt> +<dd> +<p>Select the <a href="nng_pub.7.html"><em>pub</em></a> version 0 protocol. +This protocol sends messages to <a href="nng_sub.7.html"><em>sub</em></a> version peers.</p> +</dd> +<dt class="hdlist1"><strong>--sub, --sub0</strong></dt> +<dd> +<p>Select the <a href="nng_sub.7.html"><em>sub</em></a> version 0 protocol. +This protocol receives messages from <a href="nng_pub.7.html"><em>pub</em></a> version +0 peers, and filters them based on subscriptions set with <strong>--subscribe</strong>.</p> +</dd> +<dt class="hdlist1"><strong>--push, --push0</strong></dt> +<dd> +<p>Select the <a href="nng_push.7.html"><em>push</em></a> version 0 protocol. +This protocol sends messages to <a href="nng_pull.7.html"><em>pull</em></a> version 0 peers. +A given message is normally only delivered to a single peer.</p> +</dd> +<dt class="hdlist1"><strong>--pull, --pull0</strong></dt> +<dd> +<p>Select the <a href="nng_pull.7.html"><em>pull</em></a> version 0 protocol. +This protocol receives +messages from <a href="nng_push.7.html"><em>push</em></a> version 0 peers.</p> +</dd> +<dt class="hdlist1"><strong>--pair0</strong></dt> +<dd> +<p>Select the <a href="nng_pair.7.html"><em>pair</em></a> version 0 protocol. +This protocol can send and receive messages with one connected <em>pair</em> +version 0 peer.</p> +</dd> +<dt class="hdlist1"><strong>--pair1</strong></dt> +<dd> +<p>Select the <a href="nng_pair.7.html"><em>pair</em></a> version 1 protocol. +This protocol can send and receive messages with one connected <em>pair</em> +version 1 peer. +It is not supported in <strong>--compat</strong> mode. +(Polyamorous mode is not supported +in <em>nngcat</em>, although peers may be using polyamorous mode.)</p> +</dd> +<dt class="hdlist1"><strong>--pair</strong></dt> +<dd> +<p>Acts as an alias for <strong>--pair1</strong>, unless <strong>--compat</strong> mode is selected, in +which case it acts as an alias for <strong>--pair0</strong>.</p> +</dd> +<dt class="hdlist1"><strong>--surveyor, --surveyor0</strong></dt> +<dd> +<p>Select the <a href="nng_surveyor.7.html"><em>surveyor</em></a> version 0 protocol. +This protocol sends a survey request to <a href="nng_respondent.7.html"><em>respondent</em></a> +version 0 peers, and then receives replies from them.</p> +</dd> +<dt class="hdlist1"><strong>--respondent, --respondent0</strong></dt> +<dd> +<p>Select the <a href="nng_respondent.7.html"><em>respondent</em></a> version 0 protocol. +This protocol receives survey requests from <a href="nng_surveyor.7.html"><em>surveyor</em></a> +version 0 peers, and can send a reply to them.</p> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_peer_selection_options">Peer Selection Options</h3> +<div class="admonitionblock note"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-note" title="Note"></i> +</td> +<td class="content"> +At least one peer address must be selected. +</td> +</tr> +</table> +</div> +<div class="admonitionblock tip"> +<table> +<tr> +<td class="icon"> +<i class="fa icon-tip" title="Tip"></i> +</td> +<td class="content"> +While legacy <em>nanocat</em> only supported one peer, <em>nngcat</em> can support +more than one peer on a given connection. +</td> +</tr> +</table> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><strong>--connect, --dial</strong>=<em>URL</em></dt> +<dd> +<p>Connect to the peer at the address specified by <em>URL</em>.</p> +</dd> +<dt class="hdlist1"><strong>--bind, --listen</strong>=<em>URL</em></dt> +<dd> +<p>Bind to, and accept connections from peers, at the address specified by <em>URL</em>.</p> +</dd> +<dt class="hdlist1"><strong>-x, --connect-ipc</strong>=<em>PATH</em></dt> +<dd> +<p>Connect to the IPC path specified by <em>PATH</em>. This is the same as +<strong>--connect</strong>=ipc://<em>PATH</em>.</p> +</dd> +<dt class="hdlist1"><strong>-X, --bind-ipc</strong>=<em>PATH</em></dt> +<dd> +<p>Bind to the IPC path specified by <em>PATH</em>. This is the same as +<strong>--bind</strong>=ipc://<em>PATH</em>.</p> +</dd> +<dt class="hdlist1"><strong>-l, --connect-local</strong>=<em>PORT</em></dt> +<dd> +<p>Connect to <code>localhost</code> at the TCP port specified by <em>PORT</em>. This is the same +as <strong>--connect</strong>=tcp://127.0.0.1:<em>PORT</em>.</p> +</dd> +<dt class="hdlist1"><strong>-L, --bind-local</strong>=<em>PORT</em></dt> +<dd> +<p>Bind to the TCP port specified by <em>PORT</em>. This is the same as +<strong>--bind</strong>=tcp://127.0.0.1:<em>PORT</em>.</p> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_receive_options">Receive Options</h3> +<div class="paragraph"> +<p>Data messages received can be formatted in different ways. +These options can only be specified when using a protocol that +receives messages.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><strong>-A, --ascii</strong></dt> +<dd> +<p>The same as specifying <strong>--format</strong>=<code>ascii</code>.</p> +</dd> +<dt class="hdlist1"><strong>-Q, --quoted</strong></dt> +<dd> +<p>The same as specifying <strong>--format</strong>=<code>quoted</code>.</p> +</dd> +<dt class="hdlist1"><strong>--hex</strong></dt> +<dd> +<p>The same as specifying <strong>--format</strong>=<code>hex</code>.</p> +</dd> +<dt class="hdlist1"><strong>--msgpack</strong></dt> +<dd> +<p>The same as specifying <strong>--format</strong>=<code>msgpack</code>.</p> +</dd> +<dt class="hdlist1"><strong>--raw</strong></dt> +<dd> +<p>The same as specifying <strong>--format</strong>=<code>raw</code>.</p> +</dd> +<dt class="hdlist1"><strong>--receive-timeout</strong>=<em>SEC</em></dt> +<dd> +<p>Give up receiving messages after <em>SEC</em> seconds pass without any received +messages.</p> +</dd> +<dt class="hdlist1"><strong>--recv-maxsz</strong>=<em>COUNT</em></dt> +<dd> +<p>Set the maximum message size socket will accept to <em>COUNT</em> bytes. +Messages larger than this will be discarded. +The default is 1048576 (1 MB). +To eliminate any restriction, use 0.</p> +</dd> +<dt class="hdlist1"><strong>--format</strong>=<em>FORMAT</em></dt> +<dd> +<p>Format data as indicated. The <em>FORMAT</em> can be any of:</p> +<div class="dlist"> +<dl> +<dt class="hdlist1"><code>no</code></dt> +<dd> +<p>No output at all.</p> +</dd> +<dt class="hdlist1"><code>raw</code></dt> +<dd> +<p>Raw output, every byte received is sent to standard output.</p> +</dd> +<dt class="hdlist1"><code>ascii</code></dt> +<dd> +<p>ASCII safe, printable ASCII is emitted verbatim, with other +bytes substituted with <code>.</code> (period).</p> +</dd> +<dt class="hdlist1"><code>quoted</code></dt> +<dd> +<p>Messages are printed as quoted strings, using C language +conventions.</p> +</dd> +<dt class="hdlist1"><code>hex</code></dt> +<dd> +<p> Messages are printed as quoted strings, with every byte appearing as an escaped hexadecimal value, such as <code>\x2E</code>.</p> +</dd> +<dt class="hdlist1"><code>msgpack</code></dt> +<dd> +<p> +Messages are emitted as <a href="https://msgpack.org">MessagePack</a> "bin format" +(byte arrays).</p> +</dd> +</dl> +</div> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_transmit_options">Transmit Options</h3> +<div class="paragraph"> +<p>Protocols that support sending data can use these options to select the data.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><strong>-D, --data</strong>=<em>DATA</em></dt> +<dd> +<p>Use <em>DATA</em> for the body of outgoing messages.</p> +</dd> +<dt class="hdlist1"><strong>-F, --file</strong>=<em>FILE</em></dt> +<dd> +<p>Use <em>FILE</em> for the body of outgoing messages. If <em>FILE</em> is <em>-</em> the message body will be read from standard input.</p> +</dd> +<dt class="hdlist1"><strong>-i, --interval</strong>=<em>SEC</em></dt> +<dd> +<p>For protocols that send unsolicited data (as opposed to those that +send data only in response to received messages), this will resend the +outgoing message at repeating intervals of <em>SEC</em> seconds.</p> +</dd> +<dt class="hdlist1"><strong>-d, --delay</strong>=<em>SEC</em></dt> +<dd> +<p>Wait <em>SEC</em> seconds before sending the first outgoing message. +This is useful to let connections establish before sending data, thereby +avoiding message loss.</p> +</dd> +<dt class="hdlist1"><strong>--send-timeout</strong>=<em>SEC</em></dt> +<dd> +<p>Give up trying to send a message after <em>SEC</em> seconds.</p> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_tls_options">TLS Options</h3> +<div class="paragraph"> +<p>These options are only present if TLS is configured; they are ignored +when using addresses that are not secured with TLS.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><strong>-k, --insecure</strong></dt> +<dd> +<p>Skip peer validation.</p> +</dd> +<dt class="hdlist1"><strong>-E, --cert</strong>=<em>FILE</em></dt> +<dd> +<p>Load own certificate from <em>FILE</em>.</p> +</dd> +<dt class="hdlist1"><strong>--key</strong>=<em>FILE</em></dt> +<dd> +<p>Load own key from <em>FILE</em>. +Should be used in conjunction with <strong>--cert</strong>. +If not specified, and <strong>--cert</strong> is specified, then a single file containing both +the private key and the associated certificate is assumed.</p> +</dd> +<dt class="hdlist1"><strong>--cacert</strong>=<em>FILE</em></dt> +<dd> +<p>Load CA certificates from <em>FILE</em>. +These CAs ("Certificate Authorities") are +used as trust roots when validating certificates presented by peers.</p> +</dd> +</dl> +</div> +</div> +<div class="sect2"> +<h3 id="_zerotier_options">ZeroTier Options</h3> +<div class="paragraph"> +<p>These options are only present if ZeroTier is configured; they are ignored +otherwise.</p> +</div> +<div class="dlist"> +<dl> +<dt class="hdlist1"><strong>--zt-home</strong>=<em>DIRECTORY</em></dt> +<dd> +<p>Directory for persistent ZeroTier node (key material, etc.) +This directory must already exist. +Only one program may use a ZeroTier node at a time; +file locking is used to prevent this.</p> +</dd> +</dl> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">EXAMPLES</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Echo service using request/reply.</div> +<div class="content"> +<pre class="pygments highlight"><code data-lang="sh"><span></span>$<span class="tok-w"> </span><span class="tok-nv">addr</span><span class="tok-o">=</span><span class="tok-s2">"tcp://127.0.0.1:4567"</span> +$<span class="tok-w"> </span>nngcat<span class="tok-w"> </span>--rep<span class="tok-w"> </span>--listen<span class="tok-o">=</span><span class="tok-si">${</span><span class="tok-nv">addr</span><span class="tok-si">}</span><span class="tok-w"> </span>--data<span class="tok-o">=</span><span class="tok-s2">"42"</span><span class="tok-w"> </span>--quoted<span class="tok-w"> </span><span class="tok-p">&</span> +$<span class="tok-w"> </span>nngcat<span class="tok-w"> </span>--req<span class="tok-w"> </span>--dial<span class="tok-o">=</span><span class="tok-si">${</span><span class="tok-nv">addr</span><span class="tok-si">}</span><span class="tok-w"> </span>--data<span class="tok-o">=</span><span class="tok-s2">"what is the answer?"</span><span class="tok-w"> </span>--quoted +<span class="tok-s2">"what is the answer?"</span> +<span class="tok-s2">"42"</span></code></pre> +</div> +</div> +<div class="listingblock"> +<div class="title">Send a chime every hour (3600 seconds).</div> +<div class="content"> +<pre class="pygments highlight"><code data-lang="sh"><span></span>$<span class="tok-w"> </span><span class="tok-nv">addr</span><span class="tok-o">=</span>ipc:///grandpa_clock +$<span class="tok-w"> </span>nngcat<span class="tok-w"> </span>--pub<span class="tok-w"> </span>--listen<span class="tok-o">=</span><span class="tok-si">${</span><span class="tok-nv">addr</span><span class="tok-si">}</span><span class="tok-w"> </span>--data<span class="tok-w"> </span><span class="tok-s2">"cuckoo"</span><span class="tok-w"> </span>--interval<span class="tok-w"> </span><span class="tok-m">3600</span><span class="tok-w"> </span><span class="tok-p">&</span> +$<span class="tok-w"> </span>nngcat<span class="tok-w"> </span>--sub<span class="tok-w"> </span>--dial<span class="tok-o">=</span><span class="tok-si">${</span><span class="tok-nv">addr</span><span class="tok-si">}</span><span class="tok-w"> </span>--quoted<span class="tok-w"> </span><span class="tok-p">&</span> +<span class="tok-s2">"cuckoo"</span></code></pre> +</div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">SEE ALSO</h2> +<div class="sectionbody"> +<div class="paragraph text-left"> +<p><a href="libnng.3.html">libnng(3)</a>, +<a href="nng.7.html">nng(7)</a>, +<a href="nng_bus.7.html">nng_bus(7)</a>, +<a href="nng_pair.7.html">nng_pair(7)</a>, +<a href="nng_pub.7.html">nng_pub(7)</a>, +<a href="nng_pull.7.html">nng_pull(7)</a>, +<a href="nng_push.7.html">nng_push(7)</a>, +<a href="nng_sub.7.html">nng_sub(7)</a>, +<a href="nng_rep.7.html">nng_rep(7)</a>, +<a href="nng_req.7.html">nng_req(7)</a>, +<a href="nng_respondent.7.html">nng_respondent(7)</a>, +<a href="nng_surveyor.7.html">nng_surveyor(7)</a></p> +</div> +</div> +</div> |
