From 5cf750697624d4fd63cfe26921209d7c30e1a2d2 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 21 Jan 2019 22:40:10 -0800 Subject: fixes #872 create unified nng_stream API This is a major change, and includes changes to use a polymorphic stream API for all transports. There have been related bugs fixed along the way. Additionally the man pages have changed. The old non-polymorphic APIs are removed now. This is a breaking change, but the old APIs were never part of any released public API. --- docs/man/CMakeLists.txt | 106 ++--- docs/man/libnng.3.adoc | 560 +++++++++++++------------- docs/man/man3ipc.desc | 5 - docs/man/man3ipc.sect | 1 - docs/man/man3str.desc | 7 + docs/man/man3str.sect | 1 + docs/man/nng_getopt.3.adoc | 12 +- docs/man/nng_ipc.5.adoc | 87 ---- docs/man/nng_ipc_close.3ipc.adoc | 61 --- docs/man/nng_ipc_dialer.5.adoc | 51 --- docs/man/nng_ipc_dialer_alloc.3ipc.adoc | 49 --- docs/man/nng_ipc_dialer_close.3ipc.adoc | 57 --- docs/man/nng_ipc_dialer_dial.3ipc.adoc | 65 --- docs/man/nng_ipc_dialer_free.3ipc.adoc | 54 --- docs/man/nng_ipc_dialer_getopt.3ipc.adoc | 64 --- docs/man/nng_ipc_dialer_setopt.3ipc.adoc | 59 --- docs/man/nng_ipc_free.3ipc.adoc | 59 --- docs/man/nng_ipc_getopt.3ipc.adoc | 70 ---- docs/man/nng_ipc_listener.5.adoc | 52 --- docs/man/nng_ipc_listener_accept.3ipc.adoc | 63 --- docs/man/nng_ipc_listener_alloc.3ipc.adoc | 50 --- docs/man/nng_ipc_listener_close.3ipc.adoc | 57 --- docs/man/nng_ipc_listener_free.3ipc.adoc | 52 --- docs/man/nng_ipc_listener_getopt.3ipc.adoc | 66 --- docs/man/nng_ipc_listener_listen.3ipc.adoc | 56 --- docs/man/nng_ipc_listener_setopt.3ipc.adoc | 64 --- docs/man/nng_ipc_recv.3ipc.adoc | 72 ---- docs/man/nng_ipc_send.3ipc.adoc | 71 ---- docs/man/nng_ipc_setopt.3ipc.adoc | 57 --- docs/man/nng_stream.5.adoc | 80 ++++ docs/man/nng_stream_close.3str.adoc | 65 +++ docs/man/nng_stream_dialer.5.adoc | 46 +++ docs/man/nng_stream_dialer_alloc.3str.adoc | 68 ++++ docs/man/nng_stream_dialer_close.3str.adoc | 60 +++ docs/man/nng_stream_dialer_dial.3str.adoc | 65 +++ docs/man/nng_stream_dialer_free.3str.adoc | 54 +++ docs/man/nng_stream_dialer_get.3str.adoc | 143 +++++++ docs/man/nng_stream_dialer_set.3str.adoc | 133 ++++++ docs/man/nng_stream_free.3str.adoc | 61 +++ docs/man/nng_stream_get.3str.adoc | 146 +++++++ docs/man/nng_stream_listener.5.adoc | 48 +++ docs/man/nng_stream_listener_accept.3str.adoc | 64 +++ docs/man/nng_stream_listener_alloc.3str.adoc | 70 ++++ docs/man/nng_stream_listener_close.3str.adoc | 60 +++ docs/man/nng_stream_listener_free.3str.adoc | 54 +++ docs/man/nng_stream_listener_get.3str.adoc | 144 +++++++ docs/man/nng_stream_listener_listen.3str.adoc | 66 +++ docs/man/nng_stream_listener_set.3str.adoc | 133 ++++++ docs/man/nng_stream_recv.3str.adoc | 73 ++++ docs/man/nng_stream_send.3str.adoc | 74 ++++ docs/man/nng_stream_set.3str.adoc | 133 ++++++ docs/man/nng_tcp_close.3tcp.adoc | 60 --- docs/man/nng_tcp_dialer.5.adoc | 49 --- docs/man/nng_tcp_dialer_alloc.3tcp.adoc | 50 --- docs/man/nng_tcp_dialer_close.3tcp.adoc | 57 --- docs/man/nng_tcp_dialer_dial.3tcp.adoc | 63 --- docs/man/nng_tcp_dialer_free.3tcp.adoc | 52 --- docs/man/nng_tcp_dialer_getopt.3tcp.adoc | 69 ---- docs/man/nng_tcp_dialer_setopt.3tcp.adoc | 63 --- docs/man/nng_tcp_free.3tcp.adoc | 58 --- docs/man/nng_tcp_getopt.3tcp.adoc | 68 ---- docs/man/nng_tcp_listener.5.adoc | 52 --- docs/man/nng_tcp_listener_accept.3tcp.adoc | 67 --- docs/man/nng_tcp_listener_alloc.3tcp.adoc | 51 --- docs/man/nng_tcp_listener_close.3tcp.adoc | 57 --- docs/man/nng_tcp_listener_free.3tcp.adoc | 51 --- docs/man/nng_tcp_listener_getopt.3tcp.adoc | 69 ---- docs/man/nng_tcp_listener_listen.3tcp.adoc | 71 ---- docs/man/nng_tcp_listener_setopt.3tcp.adoc | 62 --- docs/man/nng_tcp_recv.3tcp.adoc | 74 ---- docs/man/nng_tcp_send.3tcp.adoc | 73 ---- docs/man/nng_tcp_setopt.3tcp.adoc | 61 --- docs/man/nng_tls_close.3tls.adoc | 61 --- docs/man/nng_tls_dialer.5.adoc | 51 --- docs/man/nng_tls_dialer_alloc.3tls.adoc | 52 --- docs/man/nng_tls_dialer_close.3tls.adoc | 58 --- docs/man/nng_tls_dialer_dial.3tls.adoc | 65 --- docs/man/nng_tls_dialer_free.3tls.adoc | 53 --- docs/man/nng_tls_dialer_getopt.3tls.adoc | 73 ---- docs/man/nng_tls_dialer_setopt.3tls.adoc | 69 ---- docs/man/nng_tls_free.3tls.adoc | 59 --- docs/man/nng_tls_getopt.3tls.adoc | 70 ---- docs/man/nng_tls_listener.5.adoc | 53 --- docs/man/nng_tls_listener_accept.3tls.adoc | 70 ---- docs/man/nng_tls_listener_alloc.3tls.adoc | 53 --- docs/man/nng_tls_listener_close.3tls.adoc | 58 --- docs/man/nng_tls_listener_free.3tls.adoc | 52 --- docs/man/nng_tls_listener_getopt.3tls.adoc | 72 ---- docs/man/nng_tls_listener_listen.3tls.adoc | 73 ---- docs/man/nng_tls_listener_setopt.3tls.adoc | 67 --- docs/man/nng_tls_recv.3tls.adoc | 73 ---- docs/man/nng_tls_send.3tls.adoc | 72 ---- docs/man/nng_tls_setopt.3tls.adoc | 61 --- 93 files changed, 2150 insertions(+), 4310 deletions(-) delete mode 100644 docs/man/man3ipc.desc delete mode 100644 docs/man/man3ipc.sect create mode 100644 docs/man/man3str.desc create mode 100644 docs/man/man3str.sect delete mode 100644 docs/man/nng_ipc.5.adoc delete mode 100644 docs/man/nng_ipc_close.3ipc.adoc delete mode 100644 docs/man/nng_ipc_dialer.5.adoc delete mode 100644 docs/man/nng_ipc_dialer_alloc.3ipc.adoc delete mode 100644 docs/man/nng_ipc_dialer_close.3ipc.adoc delete mode 100644 docs/man/nng_ipc_dialer_dial.3ipc.adoc delete mode 100644 docs/man/nng_ipc_dialer_free.3ipc.adoc delete mode 100644 docs/man/nng_ipc_dialer_getopt.3ipc.adoc delete mode 100644 docs/man/nng_ipc_dialer_setopt.3ipc.adoc delete mode 100644 docs/man/nng_ipc_free.3ipc.adoc delete mode 100644 docs/man/nng_ipc_getopt.3ipc.adoc delete mode 100644 docs/man/nng_ipc_listener.5.adoc delete mode 100644 docs/man/nng_ipc_listener_accept.3ipc.adoc delete mode 100644 docs/man/nng_ipc_listener_alloc.3ipc.adoc delete mode 100644 docs/man/nng_ipc_listener_close.3ipc.adoc delete mode 100644 docs/man/nng_ipc_listener_free.3ipc.adoc delete mode 100644 docs/man/nng_ipc_listener_getopt.3ipc.adoc delete mode 100644 docs/man/nng_ipc_listener_listen.3ipc.adoc delete mode 100644 docs/man/nng_ipc_listener_setopt.3ipc.adoc delete mode 100644 docs/man/nng_ipc_recv.3ipc.adoc delete mode 100644 docs/man/nng_ipc_send.3ipc.adoc delete mode 100644 docs/man/nng_ipc_setopt.3ipc.adoc create mode 100644 docs/man/nng_stream.5.adoc create mode 100644 docs/man/nng_stream_close.3str.adoc create mode 100644 docs/man/nng_stream_dialer.5.adoc create mode 100644 docs/man/nng_stream_dialer_alloc.3str.adoc create mode 100644 docs/man/nng_stream_dialer_close.3str.adoc create mode 100644 docs/man/nng_stream_dialer_dial.3str.adoc create mode 100644 docs/man/nng_stream_dialer_free.3str.adoc create mode 100644 docs/man/nng_stream_dialer_get.3str.adoc create mode 100644 docs/man/nng_stream_dialer_set.3str.adoc create mode 100644 docs/man/nng_stream_free.3str.adoc create mode 100644 docs/man/nng_stream_get.3str.adoc create mode 100644 docs/man/nng_stream_listener.5.adoc create mode 100644 docs/man/nng_stream_listener_accept.3str.adoc create mode 100644 docs/man/nng_stream_listener_alloc.3str.adoc create mode 100644 docs/man/nng_stream_listener_close.3str.adoc create mode 100644 docs/man/nng_stream_listener_free.3str.adoc create mode 100644 docs/man/nng_stream_listener_get.3str.adoc create mode 100644 docs/man/nng_stream_listener_listen.3str.adoc create mode 100644 docs/man/nng_stream_listener_set.3str.adoc create mode 100644 docs/man/nng_stream_recv.3str.adoc create mode 100644 docs/man/nng_stream_send.3str.adoc create mode 100644 docs/man/nng_stream_set.3str.adoc delete mode 100644 docs/man/nng_tcp_close.3tcp.adoc delete mode 100644 docs/man/nng_tcp_dialer.5.adoc delete mode 100644 docs/man/nng_tcp_dialer_alloc.3tcp.adoc delete mode 100644 docs/man/nng_tcp_dialer_close.3tcp.adoc delete mode 100644 docs/man/nng_tcp_dialer_dial.3tcp.adoc delete mode 100644 docs/man/nng_tcp_dialer_free.3tcp.adoc delete mode 100644 docs/man/nng_tcp_dialer_getopt.3tcp.adoc delete mode 100644 docs/man/nng_tcp_dialer_setopt.3tcp.adoc delete mode 100644 docs/man/nng_tcp_free.3tcp.adoc delete mode 100644 docs/man/nng_tcp_getopt.3tcp.adoc delete mode 100644 docs/man/nng_tcp_listener.5.adoc delete mode 100644 docs/man/nng_tcp_listener_accept.3tcp.adoc delete mode 100644 docs/man/nng_tcp_listener_alloc.3tcp.adoc delete mode 100644 docs/man/nng_tcp_listener_close.3tcp.adoc delete mode 100644 docs/man/nng_tcp_listener_free.3tcp.adoc delete mode 100644 docs/man/nng_tcp_listener_getopt.3tcp.adoc delete mode 100644 docs/man/nng_tcp_listener_listen.3tcp.adoc delete mode 100644 docs/man/nng_tcp_listener_setopt.3tcp.adoc delete mode 100644 docs/man/nng_tcp_recv.3tcp.adoc delete mode 100644 docs/man/nng_tcp_send.3tcp.adoc delete mode 100644 docs/man/nng_tcp_setopt.3tcp.adoc delete mode 100644 docs/man/nng_tls_close.3tls.adoc delete mode 100644 docs/man/nng_tls_dialer.5.adoc delete mode 100644 docs/man/nng_tls_dialer_alloc.3tls.adoc delete mode 100644 docs/man/nng_tls_dialer_close.3tls.adoc delete mode 100644 docs/man/nng_tls_dialer_dial.3tls.adoc delete mode 100644 docs/man/nng_tls_dialer_free.3tls.adoc delete mode 100644 docs/man/nng_tls_dialer_getopt.3tls.adoc delete mode 100644 docs/man/nng_tls_dialer_setopt.3tls.adoc delete mode 100644 docs/man/nng_tls_free.3tls.adoc delete mode 100644 docs/man/nng_tls_getopt.3tls.adoc delete mode 100644 docs/man/nng_tls_listener.5.adoc delete mode 100644 docs/man/nng_tls_listener_accept.3tls.adoc delete mode 100644 docs/man/nng_tls_listener_alloc.3tls.adoc delete mode 100644 docs/man/nng_tls_listener_close.3tls.adoc delete mode 100644 docs/man/nng_tls_listener_free.3tls.adoc delete mode 100644 docs/man/nng_tls_listener_getopt.3tls.adoc delete mode 100644 docs/man/nng_tls_listener_listen.3tls.adoc delete mode 100644 docs/man/nng_tls_listener_setopt.3tls.adoc delete mode 100644 docs/man/nng_tls_recv.3tls.adoc delete mode 100644 docs/man/nng_tls_send.3tls.adoc delete mode 100644 docs/man/nng_tls_setopt.3tls.adoc (limited to 'docs/man') diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index 9a2cc5dd..747e1bad 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -1,6 +1,6 @@ # +# Copyright 2019 Staysail Systems, Inc. # Copyright 2018 Capitar IT Group BV -# Copyright 2018 Staysail Systems, Inc. # Copyright 2019 Devolutions # # This software is supplied under the terms of the MIT License, a @@ -272,28 +272,6 @@ if (NNG_ENABLE_DOC) nng_http_server_stop ) - set(NNG_MAN3IPC - nng_ipc_close - nng_ipc_free - nng_ipc_getopt - nng_ipc_dialer_alloc - nng_ipc_dialer_close - nng_ipc_dialer_dial - nng_ipc_dialer_free - nng_ipc_dialer_getopt - nng_ipc_dialer_setopt - nng_ipc_listener_accept - nng_ipc_listener_alloc - nng_ipc_listener_close - nng_ipc_listener_free - nng_ipc_listener_getopt - nng_ipc_listener_listen - nng_ipc_listener_setopt - nng_ipc_recv - nng_ipc_send - nng_ipc_setopt - ) - set(NNG_MAN3SUPP nng_clock nng_cv_alloc @@ -313,30 +291,29 @@ if (NNG_ENABLE_DOC) nng_thread_destroy ) - set(NNG_MAN3TCP - nng_tcp_close - nng_tcp_free - nng_tcp_getopt - nng_tcp_dialer_alloc - nng_tcp_dialer_close - nng_tcp_dialer_dial - nng_tcp_dialer_free - nng_tcp_dialer_getopt - nng_tcp_dialer_setopt - nng_tcp_listener_accept - nng_tcp_listener_alloc - nng_tcp_listener_close - nng_tcp_listener_free - nng_tcp_listener_getopt - nng_tcp_listener_listen - nng_tcp_listener_setopt - nng_tcp_recv - nng_tcp_send - nng_tcp_setopt + set(NNG_MAN3STR + nng_stream_close + nng_stream_free + nng_stream_get + nng_stream_recv + nng_stream_send + nng_stream_set + nng_stream_dialer_alloc + nng_stream_dialer_close + nng_stream_dialer_dial + nng_stream_dialer_free + nng_stream_dialer_get + nng_stream_dialer_set + nng_stream_listener_accept + nng_stream_listener_alloc + nng_stream_listener_close + nng_stream_listener_free + nng_stream_listener_get + nng_stream_listener_listen + nng_stream_listener_set ) set(NNG_MAN3TLS - nng_tls_close nng_tls_config_alloc nng_tls_config_auth_mode nng_tls_config_ca_chain @@ -346,24 +323,6 @@ if (NNG_ENABLE_DOC) nng_tls_config_hold nng_tls_config_own_cert nng_tls_config_server_name - nng_tls_free - nng_tls_getopt - nng_tls_dialer_alloc - nng_tls_dialer_close - nng_tls_dialer_dial - nng_tls_dialer_free - nng_tls_dialer_getopt - nng_tls_dialer_setopt - nng_tls_listener_accept - nng_tls_listener_alloc - nng_tls_listener_close - nng_tls_listener_free - nng_tls_listener_getopt - nng_tls_listener_listen - nng_tls_listener_setopt - nng_tls_recv - nng_tls_send - nng_tls_setopt ) set(NNG_MAN5 @@ -385,20 +344,13 @@ if (NNG_ENABLE_DOC) nng_socket nng_stat - nng_tcp - nng_tcp_dialer - nng_tcp_listener - nng_tcp_options + nng_stream + nng_stream_dialer + nng_stream_listener - nng_ipc - nng_ipc_dialer - nng_ipc_listener + nng_tcp_options nng_ipc_options - - nng_tls nng_tls_config - nng_tls_dialer - nng_tls_listener nng_tls_options ) @@ -438,18 +390,14 @@ if (NNG_ENABLE_DOC) nng_man(${F} 3http) endforeach() - foreach(F ${NNG_MAN3IPC}) - nng_man(${F} 3ipc) + foreach(F ${NNG_MAN3STR}) + nng_man(${F} 3str) endforeach() foreach(F ${NNG_MAN3SUPP}) nng_man(${F} 3supp) endforeach() - foreach(F ${NNG_MAN3TCP}) - nng_man(${F} 3tcp) - endforeach() - foreach(F ${NNG_MAN3TLS}) nng_man(${F} 3tls) endforeach() diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 49b9b78a..3aebcf76 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -20,7 +20,7 @@ libnng - nanomsg next generation library == DESCRIPTION -The <> library provides a common messaging framework +The xref:nng.7.adoc[_nng_] library provides a common messaging framework intended to solve common communication problems in distributed applications. It provides a C language API. @@ -30,12 +30,12 @@ It provides a C language API. The following common functions exist in _libnng_. |=== -|<>|allocate memory -|<>|free memory -|<>|duplicate string -|<>|return an error description -|<>|free string -|<>|report library version +|xref:nng_alloc.3.adoc[nng_alloc()]|allocate memory +|xref:nng_free.3.adoc[nng_free()]|free memory +|xref:nng_strdup.3.adoc[nng_strdup()]|duplicate string +|xref:nng_strerror.3.adoc[nng_strerror()]|return an error description +|xref:nng_strfree.3.adoc[nng_strfree()]|free string +|xref:nng_version.3.adoc[nng_version()]|report library version |=== === Socket Functions @@ -43,14 +43,14 @@ The following common functions exist in _libnng_. The following functions operate on sockets. |=== -|<>|close socket -|<>|create and start dialer -|<>|get socket option -|<>|create and start listener -|<>|receive data -|<>|send data -|<>|set socket option -|<>|get numeric socket identifier +|xref:nng_close.3.adoc[nng_close()]|close socket +|xref:nng_dial.3.adoc[nng_dial()]|create and start dialer +|xref:nng_getopt.3.adoc[nng_getopt()]|get socket option +|xref:nng_listen.3.adoc[nng_listen()]|create and start listener +|xref:nng_recv.3.adoc[nng_recv()]|receive data +|xref:nng_send.3.adoc[nng_send()]|send data +|xref:nng_setopt.3.adoc[nng_setopt()]|set socket option +|xref:nng_socket_id.3.adoc[nng_socket_id()]|get numeric socket identifier |=== === Connection Management @@ -59,27 +59,27 @@ The following functions are used with either listeners, or dialers. Listeners accept incoming connection requests, and dialers make them. |=== -|<>|create and start dialer -|<>|close dialer -|<>|create dialer -|<>|get dialer option -|<>|get numeric dialer identifier -|<>|set dialer option -|<>|start dialer -|<>|create and start listener -|<>|close listener -|<>|create listener -|<>|get listener option -|<>|get numeric listener identifier -|<>|set listener option -|<>|start listener -|<>|close pipe -|<>|return dialer that created pipe -|<>|get pipe option -|<>|get numeric pipe identifier -|<>|return listener that created pipe -|<>|register pipe notification callback -|<>|return owning socket for pipe +|xref:nng_dial.3.adoc[nng_dial()]|create and start dialer +|xref:nng_dialer_close.3.adoc[nng_dialer_close()]|close dialer +|xref:nng_dialer_create.3.adoc[nng_dialer_create()]|create dialer +|xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt()]|get dialer option +|xref:nng_dialer_id.3.adoc[nng_dialer_id()]|get numeric dialer identifier +|xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt()]|set dialer option +|xref:nng_dialer_start.3.adoc[nng_dialer_start()]|start dialer +|xref:nng_listen.3.adoc[nng_listen()]|create and start listener +|xref:nng_listener_close.3.adoc[nng_listener_close()]|close listener +|xref:nng_listener_create.3.adoc[nng_listener_create()]|create listener +|xref:nng_listener_getopt.3.adoc[nng_listener_getopt()]|get listener option +|xref:nng_listener_id.3.adoc[nng_listener_id()]|get numeric listener identifier +|xref:nng_listener_setopt.3.adoc[nng_listener_setopt()]|set listener option +|xref:nng_listener_start.3.adoc[nng_listener_start()]|start listener +|xref:nng_pipe_close.3.adoc[nng_pipe_close()]|close pipe +|xref:nng_pipe_dialer.3.adoc[nng_pipe_dialer()]|return dialer that created pipe +|xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt()]|get pipe option +|xref:nng_pipe_id.3.adoc[nng_pipe_id()]|get numeric pipe identifier +|xref:nng_pipe_listener.3.adoc[nng_pipe_listener()]|return listener that created pipe +|xref:nng_pipe_notify.3.adoc[nng_pipe_notify()]|register pipe notification callback +|xref:nng_pipe_socket.3.adoc[nng_pipe_socket()]|return owning socket for pipe |=== === Message Handling Functions @@ -93,21 +93,21 @@ user-payload and the header carries protocol specific header information. Most applications will only interact with the body. |=== -|<>|allocate a message -|<>|append to message body -|<>|return message body -|<>|remove data from end of message body -|<>|clear message body -|<>|duplicate a message -|<>|free a message -|<>|get pipe for message -|<>|prepend to message body -|<>|return the message body length -|<>|reallocate a message -|<>|set pipe for message -|<>|remove data from start of message body -|<>|receive a message -|<>|send a message +|xref:nng_msg_alloc.3.adoc[nng_msg_alloc()]|allocate a message +|xref:nng_msg_append.3.adoc[nng_msg_append()]|append to message body +|xref:nng_msg_body.3.adoc[nng_msg_body()]|return message body +|xref:nng_msg_chop.3.adoc[nng_msg_chop()]|remove data from end of message body +|xref:nng_msg_clear.3.adoc[nng_msg_clear()]|clear message body +|xref:nng_msg_dup.3.adoc[nng_msg_dup()]|duplicate a message +|xref:nng_msg_free.3.adoc[nng_msg_free()]|free a message +|xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe()]|get pipe for message +|xref:nng_msg_insert.3.adoc[nng_msg_insert()]|prepend to message body +|xref:nng_msg_len.3.adoc[nng_msg_len()]|return the message body length +|xref:nng_msg_realloc.3.adoc[nng_msg_realloc()]|reallocate a message +|xref:nng_msg_set_pipe.3.adoc[nng_msg_set_pipe()]|set pipe for message +|xref:nng_msg_trim.3.adoc[nng_msg_trim()]|remove data from start of message body +|xref:nng_recvmsg.3.adoc[nng_recvmsg()]|receive a message +|xref:nng_sendmsg.3.adoc[nng_sendmsg()]|send a message |=== ==== Message Header Handling @@ -117,19 +117,19 @@ used to carry protocol-specific content. However, applications which use raw mode may need to access the header of messages. |=== -|<>|return message header -|<>|append to message header -|<>|remove data from end of message header -|<>|clear message header -|<>|prepend to message header -|<>|return the message header length -|<>|remove data from start of message header +|xref:nng_msg_header.3.adoc[nng_msg_header()]|return message header +|xref:nng_msg_header_append.3.adoc[nng_msg_header_append()]|append to message header +|xref:nng_msg_header_chop.3.adoc[nng_msg_header_chop()]|remove data from end of message header +|xref:nng_msg_header_clear.3.adoc[nng_msg_header_clear()]|clear message header +|xref:nng_msg_header_insert.3.adoc[nng_msg_header_insert()]|prepend to message header +|xref:nng_msg_header_len.3.adoc[nng_msg_header_len()]|return the message header length +|xref:nng_msg_header_trim.3.adoc[nng_msg_header_trim()]|remove data from start of message header |=== === Asynchronous Operations Most applications will interact with _nng_ synchronously; that is that -functions such as <> will block the calling +functions such as xref:nng_send.3.adoc[`nng_send()`] will block the calling thread until the operation has completed. NOTE: Synchronous operations which send messages may return before the @@ -143,7 +143,7 @@ the calling thread. When the operation is subsequently completed (regardless of whether this was successful or not), then a user supplied function ("`callback`") is executed. -A context structure, an <>, is allocated and +A context structure, an xref:nng_aio.5.adoc[`nng_aio`], is allocated and associated with each asynchronous operation. Only a single asynchronous operation may be associated with an `nng_aio` at any time. @@ -151,28 +151,28 @@ Only a single asynchronous operation may be associated with an The following functions are used in the asynchronous model: |=== -|<>|abort asynchronous I/O operation -|<>|allocate asynchronous I/O handle -|<>|begin asynchronous I/O operation -|<>|cancel asynchronous I/O operation -|<>|return number of bytes transferred -|<>|defer asynchronous I/O operation -|<>|finish asynchronous I/O operation -|<>|free asynchronous I/O handle -|<>|return input parameter -|<>|get message from an asynchronous receive -|<>|return output result -|<>|return result of asynchronous operation -|<>|set input parameter -|<>|set scatter/gather vector -|<>|set message for an asynchronous send -|<>|set output result -|<>|set asynchronous I/O timeout -|<>|stop asynchronous I/O operation -|<>|wait for asynchronous I/O operation -|<>|receive message asynchronously -|<>|send message asynchronously -|<>|sleep asynchronously +|xref:nng_aio_abort.3.adoc[nng_aio_abort()]|abort asynchronous I/O operation +|xref:nng_aio_alloc.3.adoc[nng_aio_alloc()]|allocate asynchronous I/O handle +|xref:nng_aio_begin.3.adoc[nng_aio_begin()]|begin asynchronous I/O operation +|xref:nng_aio_cancel.3.adoc[nng_aio_cancel()]|cancel asynchronous I/O operation +|xref:nng_aio_count.3.adoc[nng_aio_count()]|return number of bytes transferred +|xref:nng_aio_defer.3.adoc[nng_aio_defer()]|defer asynchronous I/O operation +|xref:nng_aio_finish.3.adoc[nng_aio_finish()]|finish asynchronous I/O operation +|xref:nng_aio_free.3.adoc[nng_aio_free()]|free asynchronous I/O handle +|xref:nng_aio_get_input.3.adoc[nng_aio_get_input()]|return input parameter +|xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg()]|get message from an asynchronous receive +|xref:nng_aio_get_output.3.adoc[nng_aio_get_output()]|return output result +|xref:nng_aio_result.3.adoc[nng_aio_result()]|return result of asynchronous operation +|xref:nng_aio_set_input.3.adoc[nng_aio_set_input()]|set input parameter +|xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov()]|set scatter/gather vector +|xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg()]|set message for an asynchronous send +|xref:nng_aio_set_output.3.adoc[nng_aio_set_output()]|set output result +|xref:nng_aio_set_timeout.3.adoc[nng_aio_set_timeout()]|set asynchronous I/O timeout +|xref:nng_aio_stop.3.adoc[nng_aio_stop()]|stop asynchronous I/O operation +|xref:nng_aio_wait.3.adoc[nng_aio_wait()]|wait for asynchronous I/O operation +|xref:nng_recv_aio.3.adoc[nng_recv_aio()]|receive message asynchronously +|xref:nng_send_aio.3.adoc[nng_send_aio()]|send message asynchronously +|xref:nng_sleep_aio.3.adoc[nng_sleep_aio()]|sleep asynchronously |=== === Protocols @@ -180,16 +180,16 @@ The following functions are used in the asynchronous model: The following functions are used to construct a socket with a specific protocol: |=== -|<>|open a bus socket -|<>|open a pair socket -|<>|open a pub socket -|<>|open a pull socket -|<>|open a push socket -|<>|open a rep socket -|<>|open a req socket -|<>|open a respondent socket -|<>|open a sub socket -|<>|open a surveyor socket +|xref:nng_bus_open.3.adoc[nng_bus_open()]|open a bus socket +|xref:nng_pair_open.3.adoc[nng_pair_open()]|open a pair socket +|xref:nng_pub_open.3.adoc[nng_pub_open()]|open a pub socket +|xref:nng_pull_open.3.adoc[nng_pull_open()]|open a pull socket +|xref:nng_push_open.3.adoc[nng_push_open()]|open a push socket +|xref:nng_rep_open.3.adoc[nng_rep_open()]|open a rep socket +|xref:nng_req_open.3.adoc[nng_req_open()]|open a req socket +|xref:nng_respondent_open.3.adoc[nng_respondent_open()]|open a respondent socket +|xref:nng_sub_open.3.adoc[nng_sub_open()]|open a sub socket +|xref:nng_surveyor_open.3.adoc[nng_surveyor_open()]|open a surveyor socket |=== === Transports @@ -197,13 +197,13 @@ The following functions are used to construct a socket with a specific protocol: The following functions are used to register a transport for use. |=== -| <>|register inproc transport -| <>|register IPC transport -| <>|register TCP transport -| <>|register TLS transport -| <>|register WebSocket transport -| <>|register WebSocket Secure transport -| <>|register ZeroTier transport +| xref:nng_inproc_register.3.adoc[nng_inproc_register()]|register inproc transport +| xref:nng_ipc_register.3.adoc[nng_ipc_register()]|register IPC transport +| xref:nng_tcp_register.3.adoc[nng_tcp_register()]|register TCP transport +| xref:nng_tls_register.3.adoc[nng_tls_register()]|register TLS transport +| xref:nng_ws_register.3.adoc[nng_ws_register()]|register WebSocket transport +| xref:nng_wss_register.3.adoc[nng_wss_register()]|register WebSocket Secure transport +| xref:nng_zt_register.3.adoc[nng_zt_register()]|register ZeroTier transport |=== === Protocol Contexts @@ -214,13 +214,13 @@ This can allow multiple contexts to be created on a single socket for concurrent applications. |=== -|<>|close context -|<>|get context option -|<>|get numeric context identifier -|<>|create context -|<>|receive message using context asynchronously -|<>|send message using context asynchronously -|<>|set context option +|xref:nng_ctx_close.3.adoc[nng_ctx_close()]|close context +|xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt()]|get context option +|xref:nng_ctx_id.3.adoc[nng_ctx_id()]|get numeric context identifier +|xref:nng_ctx_open.3.adoc[nng_ctx_open()]|create context +|xref:nng_ctx_recv.3.adoc[nng_ctx_recv()]|receive message using context asynchronously +|xref:nng_ctx_send.3.adoc[nng_ctx_send()]|send message using context asynchronously +|xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt()]|set context option |=== === Statistics @@ -229,17 +229,17 @@ The following functions provide access to statistics which can be used to observe program behaviors and as an aid in troubleshooting. |=== -|<>|get child statistic -|<>|get statistic description -|<>|get statistic name -|<>|get next statistic -|<>|get statistic string value -|<>|get statistic timestamp -|<>|get statistic type -|<>|get statistic unit -|<>|get statistic value -|<>|free statistics -|<>|get statistics +|xref:nng_stat_child.3.adoc[nng_stat_child()]|get child statistic +|xref:nng_stat_desc.3.adoc[nng_stat_name()]|get statistic description +|xref:nng_stat_name.3.adoc[nng_stat_name()]|get statistic name +|xref:nng_stat_next.3.adoc[nng_stat_next()]|get next statistic +|xref:nng_stat_string.3.adoc[nng_stat_string()]|get statistic string value +|xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp()]|get statistic timestamp +|xref:nng_stat_type.3.adoc[nng_stat_type()]|get statistic type +|xref:nng_stat_unit.3.adoc[nng_stat_unit()]|get statistic unit +|xref:nng_stat_value.3.adoc[nng_stat_valueg()]|get statistic value +|xref:nng_stats_free.3.adoc[nng_stats_free()]|free statistics +|xref:nng_stats_get.3.adoc[nng_stats_get()]|get statistics |=== === URL Object @@ -248,9 +248,9 @@ Common functionality is supplied for parsing and handling universal resource locators (URLS). |=== -|<>|clone URL structure -|<>|free URL structure -|<>|create URL structure from string +|xref:nng_url_clone.3.adoc[nng_url_clone()]|clone URL structure +|xref:nng_url_free.3.adoc[nng_url_free()]|free URL structure +|xref:nng_url_parse.3.adoc[nng_url_parse()]|create URL structure from string |=== @@ -261,79 +261,57 @@ network applications with _NNG_, but they are made available as a convenience to aid in creating portable applications. |=== -|<>|get time -|<>|allocate condition variable -|<>|free condition variable -|<>|wait for condition or timeout -|<>|wait for condition -|<>|wake all waiters -|<>|wake one waiter -|<>|sleep for milliseconds -|<>|allocate mutex -|<>|free mutex -|<>|lock mutex -|<>|unlock mutex -|<>|parse command line options -|<>|get random number -|<>|create thread -|<>|reap thread -|=== - - -=== Supplemental TCP - -These TCP functions are available for use with direct TCP access. -Most applications won't need to use these. - -|=== -|<>|close TCP connection -|<>|allocate TCP dialer -|<>|close TCP dialer -|<>|initiate outgoing TCP connection -|<>|free TCP dialer -|<>|get option from TCP dialer -|<>|set option on TCP dialer -|<>|free TCP connection -|<>|get option from TCP connection -|<>|accept incoming TCP connection -|<>|allocate TCP listener -|<>|close TCP listener -|<>|free TCP listener -|<>|get option from TCP listener -|<>|bind TCP listener to port -|<>|set option on TCP listener -|<>|receive from TCP connection -|<>|send to TCP connection -|<>|set option on TCP connection -|=== - - -=== Supplemental IPC - -These IPC functions are available for use with direct interprocess -communication (IPC). -Most applications won't need to use these. - -|=== -|<>|close IPC connection -|<>|allocate IPC dialer -|<>|close IPC dialer -|<>|initiate outgoing IPC connection -|<>|free IPC dialer -|<>|get option from IPC dialer -|<>|set option on IPC dialer -|<>|free IPC connection -|<>|get option from IPC connection -|<>|accept incoming IPC connection -|<>|allocate IPC listener -|<>|close IPC listener -|<>|free IPC listener -|<>|get option from IPC listener -|<>|bind IPC listener -|<>|set option on IPC listener -|<>|receive from IPC connection -|<>|send to IPC connection -|<>|set option on IPC connection +|xref:nng_clock.3supp.adoc[nng_clock()]|get time +|xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc()]|allocate condition variable +|xref:nng_cv_free.3supp.adoc[nng_cv_free()]|free condition variable +|xref:nng_cv_until.3supp.adoc[nng_cv_until()]|wait for condition or timeout +|xref:nng_cv_wait.3supp.adoc[nng_cv_wait()]|wait for condition +|xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters +|xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter +|xref:nng_msleep.3supp.adoc[nng_msleep()]|sleep for milliseconds +|xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc()]|allocate mutex +|xref:nng_mtx_free.3supp.adoc[nng_mtx_free()]|free mutex +|xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock()]|lock mutex +|xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex +|xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options +|xref:nng_random.3supp.adoc[nng_random()]|get random number +|xref:nng_thread_create.3supp.adoc[nng_thread_create()]|create thread +|xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy()]|reap thread +|=== + +=== Byte Streams + +These functions are available for use with byte streams. +They are considered low-level, for uses where the higher level functions +using Scalability Protocols are inappropriate. + +Byte streams, represented by +xref:nng_stream.5.adoc[`nng_stream`] objects, correspond to underlying +connections such as TCP connections or named pipes. +They are created by either +xref:nng_stream_dialer.5.adoc[`nng_stream_dialer`] or +xref:nng_stream_listener.5.adoc[`nng_stream_listener`] objects. + +|=== +|xref:nng_stream_close.3str.adoc[nng_stream_close()]|close byte stream +|xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc()]|allocate byte stream dialer +|xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close()]|close byte stream dialer +|xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial()]|initiate outgoing byte stream +|xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free()]|free byte stream dialer +|xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get()]|get option from byte stream dialer +|xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set()]|set option on byte stream dialer +|xref:nng_stream_free.3str.adoc[nng_stream_free()]|free byte stream +|xref:nng_stream_get.3str.adoc[nng_stream_get()]|get option from byte stream +|xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept()]|accept incoming byte stream +|xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc()]|allocate byte stream listener +|xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close()]|close byte stream listener +|xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free()]|free byte stream listener +|xref:nng_stream_listener_get.3str.adoc[nng_stream_listener_get()]|get option from byte stream listener +|xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen()]|bind byte stream listener to address +|xref:nng_stream_listener_set.3str.adoc[nng_stream_listener_set()]|set option on byte stream listener +|xref:nng_stream_recv.3str.adoc[nng_stream_recv()]|receive from byte stream +|xref:nng_stream_send.3str.adoc[nng_stream_send()]|send to byte stream +|xref:nng_stream_set.3str.adoc[nng_stream_set()]|set option on byte stream |=== === HTTP Support @@ -349,48 +327,48 @@ The following functions are used to work with HTTP requests, responses, and connections. |=== -|<>|close HTTP connection -|<>|read from HTTP connection -|<>|read all from HTTP connection -|<>|read HTTP request -|<>|read HTTP response -|<>|write to HTTP connection -|<>|write all to HTTP connection -|<>|write HTTP request -|<>|write HTTP response -|<>|add HTTP request header -|<>|allocate HTTP request structure -|<>|copy HTTP request body -|<>|delete HTTP request header -|<>|free HTTP request structure -|<>|get HTTP request body -|<>|return HTTP request header -|<>|return HTTP request method -|<>|return HTTP request URI -|<>|return HTTP request protocol version -|<>|reset HTTP request structure -|<>|set HTTP request body -|<>|set HTTP request header -|<>|set HTTP request method -|<>|set HTTP request URI -|<>|set HTTP request protocol version -|<>|add HTTP response header -|<>|allocate HTTP response structure -|<>|allocate HTTP error response -|<>|copy HTTP response body -|<>|delete HTTP response header -|<>|free HTTP response structure -|<>|get HTTP response body -|<>|return HTTP response header -|<>|return HTTP response reason -|<>|return HTTP response status -|<>|return HTTP response protocol version -|<>|reset HTTP response structure -|<>|set HTTP response body -|<>|set HTTP response header -|<>|set HTTP response reason -|<>|set HTTP response status -|<>|set HTTP response protocol version +|xref:nng_http_conn_close.3http.adoc[nng_http_conn_close()]|close HTTP connection +|xref:nng_http_conn_read.3http.adoc[nng_http_conn_read()]|read from HTTP connection +|xref:nng_http_conn_read_all.3http.adoc[nng_http_conn_read_all()]|read all from HTTP connection +|xref:nng_http_conn_read_req.3http.adoc[nng_http_conn_read_req()]|read HTTP request +|xref:nng_http_conn_read_res.3http.adoc[nng_http_conn_read_res()]|read HTTP response +|xref:nng_http_conn_write.3http.adoc[nng_http_conn_write()]|write to HTTP connection +|xref:nng_http_conn_write_all.3http.adoc[nng_http_conn_write_all()]|write all to HTTP connection +|xref:nng_http_conn_write_req.3http.adoc[nng_http_conn_write_req()]|write HTTP request +|xref:nng_http_conn_write_res.3http.adoc[nng_http_conn_write_res()]|write HTTP response +|xref:nng_http_req_add_header.3http.adoc[nng_http_req_add_header()]|add HTTP request header +|xref:nng_http_req_alloc.3http.adoc[nng_http_req_alloc()]|allocate HTTP request structure +|xref:nng_http_req_copy_data.3http.adoc[nng_http_req_copy_data()]|copy HTTP request body +|xref:nng_http_req_del_header.3http.adoc[nng_http_req_del_header()]|delete HTTP request header +|xref:nng_http_req_free.3http.adoc[nng_http_req_free()]|free HTTP request structure +|xref:nng_http_req_get_data.3http.adoc[nng_http_req_get_data()]|get HTTP request body +|xref:nng_http_req_get_header.3http.adoc[nng_http_req_get_header()]|return HTTP request header +|xref:nng_http_req_get_method.3http.adoc[nng_http_req_get_method()]|return HTTP request method +|xref:nng_http_req_get_uri.3http.adoc[nng_http_req_get_uri()]|return HTTP request URI +|xref:nng_http_req_get_version.3http.adoc[nng_http_req_get_version()]|return HTTP request protocol version +|xref:nng_http_req_reset.3http.adoc[nng_http_req_reset()]|reset HTTP request structure +|xref:nng_http_req_set_data.3http.adoc[nng_http_req_set_data()]|set HTTP request body +|xref:nng_http_req_set_header.3http.adoc[nng_http_req_set_header()]|set HTTP request header +|xref:nng_http_req_set_method.3http.adoc[nng_http_req_set_method()]|set HTTP request method +|xref:nng_http_req_set_uri.3http.adoc[nng_http_req_set_uri()]|set HTTP request URI +|xref:nng_http_req_set_version.3http.adoc[nng_http_req_set_version()]|set HTTP request protocol version +|xref:nng_http_res_add_header.3http.adoc[nng_http_res_add_header()]|add HTTP response header +|xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc()]|allocate HTTP response structure +|xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error()]|allocate HTTP error response +|xref:nng_http_res_copy_data.3http.adoc[nng_http_res_copy_data()]|copy HTTP response body +|xref:nng_http_res_del_header.3http.adoc[nng_http_res_del_header()]|delete HTTP response header +|xref:nng_http_res_free.3http.adoc[nng_http_res_free()]|free HTTP response structure +|xref:nng_http_res_get_data.3http.adoc[nng_http_res_get_data()]|get HTTP response body +|xref:nng_http_res_get_header.3http.adoc[nng_http_res_get_header()]|return HTTP response header +|xref:nng_http_res_get_reason.3http.adoc[nng_http_res_get_reason()]|return HTTP response reason +|xref:nng_http_res_get_status.3http.adoc[nng_http_res_get_status()]|return HTTP response status +|xref:nng_http_res_get_version.3http.adoc[nng_http_res_get_version()]|return HTTP response protocol version +|xref:nng_http_res_reset.3http.adoc[nng_http_res_reset()]|reset HTTP response structure +|xref:nng_http_res_set_data.3http.adoc[nng_http_res_set_data()]|set HTTP response body +|xref:nng_http_res_set_header.3http.adoc[nng_http_res_set_header()]|set HTTP response header +|xref:nng_http_res_set_reason.3http.adoc[nng_http_res_set_reason()]|set HTTP response reason +|xref:nng_http_res_set_status.3http.adoc[nng_http_res_set_status()]|set HTTP response status +|xref:nng_http_res_set_version.3http.adoc[nng_http_res_set_version()]|set HTTP response protocol version |=== ==== HTTP Client Functions @@ -398,13 +376,13 @@ and connections. These functions are intended for use with HTTP client applications. |=== -|<>|allocate HTTP client -|<>|establish HTTP client connection -|<>|free HTTP client -|<>|get HTTP client TLS configuration -|<>|set HTTP client TLS configuration -|<>|perform one HTTP transaction -|<>|perform one HTTP transaction on connection +|xref:nng_http_client_alloc.3http.adoc[nng_http_client_alloc()]|allocate HTTP client +|xref:nng_http_client_connect.3http.adoc[nng_http_client_connect()]|establish HTTP client connection +|xref:nng_http_client_free.3http.adoc[nng_http_client_free()]|free HTTP client +|xref:nng_http_client_get_tls.3http.adoc[nng_http_client_get_tls()]|get HTTP client TLS configuration +|xref:nng_http_client_set_tls.3http.adoc[nng_http_client_set_tls()]|set HTTP client TLS configuration +|xref:nng_http_client_transact.3http.adoc[nng_http_client_transact()]|perform one HTTP transaction +|xref:nng_http_conn_transact.3http.adoc[nng_http_conn_transact()]|perform one HTTP transaction on connection |=== ==== HTTP Server Functions @@ -412,26 +390,26 @@ These functions are intended for use with HTTP client applications. These functions are intended for use with HTTP server applications. |=== -|<>|allocate HTTP server handler -|<>|set HTTP handler to collect request body -|<>|free HTTP server handler -|<>|return extra data for HTTP handler -|<>|set extra data for HTTP handler -|<>|set host for HTTP handler -|<>|set HTTP handler method -|<>|set HTTP handler to match trees -|<>|hijack HTTP server connection -|<>|add HTTP server handler -|<>|delete HTTP server handler -|<>|get HTTP server TLS configuration -|<>|get and hold HTTP server instance -|<>|release HTTP server instance -|<>|set custom HTTP error file -|<>|set custom HTTP error page -|<>|set HTTP server TLS configuration -|<>|use HTTP server error page -|<>|start HTTP server -|<>|stop HTTP server +|xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc()]|allocate HTTP server handler +|xref:nng_http_handler_collect_body.3http.adoc[nng_http_handler_collect_body()]|set HTTP handler to collect request body +|xref:nng_http_handler_free.3http.adoc[nng_http_handler_free()]|free HTTP server handler +|xref:nng_http_handler_get_data.3http.adoc[nng_http_handler_get_data()]|return extra data for HTTP handler +|xref:nng_http_handler_set_data.3http.adoc[nng_http_handler_set_data()]|set extra data for HTTP handler +|xref:nng_http_handler_set_host.3http.adoc[nng_http_handler_set_host()]|set host for HTTP handler +|xref:nng_http_handler_set_method.3http.adoc[nng_http_handler_set_method()]|set HTTP handler method +|xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree()]|set HTTP handler to match trees +|xref:nng_http_hijack.3http.adoc[nng_http_hijack()]|hijack HTTP server connection +|xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler()]|add HTTP server handler +|xref:nng_http_server_del_handler.3http.adoc[nng_http_server_del_handler()]|delete HTTP server handler +|xref:nng_http_server_get_tls.3http.adoc[nng_http_server_get_tls()]|get HTTP server TLS configuration +|xref:nng_http_server_hold.3http.adoc[nng_http_server_hold()]|get and hold HTTP server instance +|xref:nng_http_server_release.3http.adoc[nng_http_server_release()]|release HTTP server instance +|xref:nng_http_server_set_error_file.3http.adoc[nng_http_server_set_error_file()]|set custom HTTP error file +|xref:nng_http_server_set_error_page.3http.adoc[nng_http_server_set_error_page()]|set custom HTTP error page +|xref:nng_http_server_set_tls.3http.adoc[nng_http_server_set_tls()]|set HTTP server TLS configuration +|xref:nng_http_server_res_error.3http.adoc[nng_http_server_res_error()]|use HTTP server error page +|xref:nng_http_server_start.3http.adoc[nng_http_server_start()]|start HTTP server +|xref:nng_http_server_stop.3http.adoc[nng_http_server_stop()]|stop HTTP server |=== === TLS Configuration Objects @@ -444,38 +422,38 @@ NOTE: These functions will only be present if the library has been built with TLS support. |=== -|<>|close TLS connection -|<>|allocate TLS configuration -|<>|set authentication mode -|<>|set certificate authority chain -|<>|load certificate authority from file -|<>|load own certificate and key from file -|<>|set own certificate and key -|<>|free TLS configuration -|<>|set remote server name -|<>|allocate TLS dialer -|<>|close TLS dialer -|<>|initiate outgoing TLS connection -|<>|free TLS dialer -|<>|get option from TLS dialer -|<>|set option on TLS dialer -|<>|free TLS connection -|<>|get option from TLS connection -|<>|accept incoming TLS connection -|<>|allocate TLS listener -|<>|close TLS listener -|<>|free TLS listener -|<>|get option from TLS listener -|<>|bind TLS listener to port -|<>|set option on TLS listener -|<>|receive from TLS connection -|<>|send to TLS connection -|<>|set option on TLS connection +|xref:nng_tls_close.3tls.adoc[nng_tls_close()]|close TLS connection +|xref:nng_tls_config_alloc.3tls.adoc[nng_tls_config_alloc()]|allocate TLS configuration +|xref:nng_tls_config_auth_mode.3tls.adoc[nng_tls_config_auth_mode()]|set authentication mode +|xref:nng_tls_config_ca_chain.3tls.adoc[nng_tls_config_ca_chain()]|set certificate authority chain +|xref:nng_tls_config_ca_file.3tls.adoc[nng_tls_config_ca_file()]|load certificate authority from file +|xref:nng_tls_config_cert_key_file.3tls.adoc[nng_tls_config_cert_key_file()]|load own certificate and key from file +|xref:nng_tls_config_own_cert.3tls.adoc[nng_tls_config_own_cert()]|set own certificate and key +|xref:nng_tls_config_free.3tls.adoc[nng_tls_config_free()]|free TLS configuration +|xref:nng_tls_config_server_name.3tls.adoc[nng_tls_config_server_name()]|set remote server name +|xref:nng_tls_dialer_alloc.3tls.adoc[nng_tls_dialer_alloc()]|allocate TLS dialer +|xref:nng_tls_dialer_close.3tls.adoc[nng_tls_dialer_close()]|close TLS dialer +|xref:nng_tls_dialer_dial.3tls.adoc[nng_tls_dialer_dial()]|initiate outgoing TLS connection +|xref:nng_tls_dialer_free.3tls.adoc[nng_tls_dialer_free()]|free TLS dialer +|xref:nng_tls_dialer_getopt.3tls.adoc[nng_tls_dialer_getopt()]|get option from TLS dialer +|xref:nng_tls_dialer_setopt.3tls.adoc[nng_tls_dialer_setopt()]|set option on TLS dialer +|xref:nng_tls_free.3tls.adoc[nng_tls_free()]|free TLS connection +|xref:nng_tls_getopt.3tls.adoc[nng_tls_getopt()]|get option from TLS connection +|xref:nng_tls_listener_accept.3tls.adoc[nng_tls_listener_accept()]|accept incoming TLS connection +|xref:nng_tls_listener_alloc.3tls.adoc[nng_tls_listener_alloc()]|allocate TLS listener +|xref:nng_tls_listener_close.3tls.adoc[nng_tls_listener_close()]|close TLS listener +|xref:nng_tls_listener_free.3tls.adoc[nng_tls_listener_free()]|free TLS listener +|xref:nng_tls_listener_getopt.3tls.adoc[nng_tls_listener_getopt()]|get option from TLS listener +|xref:nng_tls_listener_listen.3tls.adoc[nng_tls_listener_listen()]|bind TLS listener to port +|xref:nng_tls_listener_setopt.3tls.adoc[nng_tls_listener_setopt()]|set option on TLS listener +|xref:nng_tls_recv.3tls.adoc[nng_tls_recv()]|receive from TLS connection +|xref:nng_tls_send.3tls.adoc[nng_tls_send()]|send to TLS connection +|xref:nng_tls_setopt.3tls.adoc[nng_tls_setopt()]|set option on TLS connection |=== == SEE ALSO [.text-left] -<>, -<> +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/man/man3ipc.desc b/docs/man/man3ipc.desc deleted file mode 100644 index c38f257e..00000000 --- a/docs/man/man3ipc.desc +++ /dev/null @@ -1,5 +0,0 @@ -This section documents supplemental TCP functions that are available. - -These functions are made available to facilitate using raw TCP connections -with the NNG asynchronous I/O API. -Most applications should never need to use these functions. diff --git a/docs/man/man3ipc.sect b/docs/man/man3ipc.sect deleted file mode 100644 index ed1b8306..00000000 --- a/docs/man/man3ipc.sect +++ /dev/null @@ -1 +0,0 @@ -Supplemental TCP Functions diff --git a/docs/man/man3str.desc b/docs/man/man3str.desc new file mode 100644 index 00000000..e1fe5f9e --- /dev/null +++ b/docs/man/man3str.desc @@ -0,0 +1,7 @@ +This section documents supplemental byte stream functions that +are available. + +These functions are made available to facilitate using raw byte stream +connections with the NNG asynchronous I/O API. +These byte streams may be useful for applications that need to +communicate with raw TCP/IP or IPC streams instead of Scalability Protocols. diff --git a/docs/man/man3str.sect b/docs/man/man3str.sect new file mode 100644 index 00000000..ed1b8306 --- /dev/null +++ b/docs/man/man3str.sect @@ -0,0 +1 @@ +Supplemental TCP Functions diff --git a/docs/man/nng_getopt.3.adoc b/docs/man/nng_getopt.3.adoc index 06d6ac19..491d6038 100644 --- a/docs/man/nng_getopt.3.adoc +++ b/docs/man/nng_getopt.3.adoc @@ -59,25 +59,25 @@ on the actual option, and will be documented with the option itself. 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 _val_, and the size of the buffer shall be stored at the location referenced by -_valszp_. + - + +_valszp_. ++ 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 _valszp_. 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 _valszp_ does not exceed the original buffer size. + - + +returned size in _valszp_ does not exceed the original buffer size. ++ It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. This can be used to determine the size of the buffer needed to receive the object. - ++ TIP: It may be easier to use one of the typed forms of this function. `nng_getopt_bool()`:: This function is for options which take a Boolean (`bool`). -The value will be stored at _ivalp_. +The value will be stored at _bvalp_. `nng_getopt_int()`:: This function is for options which take an integer (`int`). diff --git a/docs/man/nng_ipc.5.adoc b/docs/man/nng_ipc.5.adoc deleted file mode 100644 index 93a131e0..00000000 --- a/docs/man/nng_ipc.5.adoc +++ /dev/null @@ -1,87 +0,0 @@ -= nng_ipc(5) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc - IPC connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_ipc_s nng_ipc; ----- - -== DESCRIPTION - -An `nng_ipc` (((IPC connection))) represents a connected stream -using interprocess communication (IPC). -IPC stream objects can be used to send or receive data. - -NOTE: The `nng_ipc` object is used for raw IPC connections, and -should not be confused with a pipe object created using the -<> transport. - -TIP: Most NNG applications should not use this, but instead use the -<> transport instead. - -These objects are created either establishing an outgoing connection -with <> or by -accepting in incoming connection with -<>. - -IPC connections are byte streams, and are "`reliable`" in that data -will not be delivered out of order, or with portions missing. - -Data can be sent using <> or -received with <>. - -When the connection is no longer needed, it should be freed with -<>. - -TIP: It is possible to close the connection, without freeing it, by -using <>. - -=== Options - -The following options are applicable to IPC connections, and may be -accessed using the <> and -<> functions. - -* <> -* <> -* <> -* <> -* <> -* <> - -Other platform specific options may be available as well. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_close.3ipc.adoc b/docs/man/nng_ipc_close.3ipc.adoc deleted file mode 100644 index df490013..00000000 --- a/docs/man/nng_ipc_close.3ipc.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= nng_ipc_close(3ipc) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_close - close IPC connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_ipc_close(nng_ipc *conn); ----- - -== DESCRIPTION - -The `nng_ipc_close()` function closes the supplied IPC connection, _conn_. - -If any operations are pending (such as <> -or <>) they will be terminated with -an `NNG_ECLOSED` error condition. -Also, any new operations will fail with `NNG_ECLOSED` after the connection -is closed. - -NOTE: 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. - -NOTE: 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 <>. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_dialer.5.adoc b/docs/man/nng_ipc_dialer.5.adoc deleted file mode 100644 index 23eb1c55..00000000 --- a/docs/man/nng_ipc_dialer.5.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= nng_ipc_dialer(5) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_dialer - IPC dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_ipc_dialer_s nng_ipc_dialer; ----- - -== DESCRIPTION - -(((IPC, dialer))) -An `nng_ipc_dialer` is a handle to an IPC "`dialer`", which is responsible for -creating connections (<> objects) by connecting to -remote systems. - -NOTE: The `nng_ipc_dialer` object is used for raw IPC connections, and -should not be confused with a dialer object created using the -<> transport. - -TIP: Most NNG applications should not use this, but instead use the -<> transport instead. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_dialer_alloc.3ipc.adoc b/docs/man/nng_ipc_dialer_alloc.3ipc.adoc deleted file mode 100644 index 6b2c1fbb..00000000 --- a/docs/man/nng_ipc_dialer_alloc.3ipc.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= nng_ipc_dialer_alloc(3ipc) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_dialer_alloc - allocate IPC dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_ipc_dialer_alloc(nng_ipc_dialer *dp); ----- - -== DESCRIPTION - -The `nng_ipc_dialer_alloc()` allocates an IPC dialer, which can be used -to create outgoing connections over IPC, and stores a pointer to it -it in the location referenced by _dp_. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_dialer_close.3ipc.adoc b/docs/man/nng_ipc_dialer_close.3ipc.adoc deleted file mode 100644 index 013274eb..00000000 --- a/docs/man/nng_ipc_dialer_close.3ipc.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= nng_ipc_dialer_close(3ipc) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_dialer_close - close IPC dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_ipc_dialer_close(nng_ipc_dialer *d); ----- - -== DESCRIPTION - -The `nng_ipc_dialer_close()` function closes the supplied IPC dialer _d_, -but does not free the underlying resources associated with it. - -If any <> operations using _d_ are -in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -Furthermore any future accesses to the dialer _d_ will also result in -`NNG_ECLOSED`. - -NOTE: This function does not release the memory for the dialer, so the -application should still free the memory using -<> -once it is certain that nothing else is using it. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_dialer_dial.3ipc.adoc b/docs/man/nng_ipc_dialer_dial.3ipc.adoc deleted file mode 100644 index 09d4dc02..00000000 --- a/docs/man/nng_ipc_dialer_dial.3ipc.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= nng_ipc_dialer_dial(3ipc) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_dialer_dial - initiate outgoing IPC connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_ipc_dialer_dial(nng_ipc_dialer *d, const nng_sockaddr *sa, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_ipc_dialer_dial()` attempts to establish an IPC connection to the -remote peer identified by _sa_, using the dialer _d_. -The operation is completed asynchronously, using _aio_. - -The address _sa_ must be in the `NNG_AF_IPC` family, -and have a valid path for IPC. - -If a connection is successfully established, the _aio_ will have the -resulting <> stored as its first output. -(See <>.) - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_EADDRINVAL`:: The address specified is invalid. -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECLOSED`:: The dialer is closed. -`NNG_ECONNREFUSED`:: The connection was refused by the server. -`NNG_ECONNRESET`:: The connection was reset by the server. -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_EPERM`:: Insufficient permission to access the IPC path. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_dialer_free.3ipc.adoc b/docs/man/nng_ipc_dialer_free.3ipc.adoc deleted file mode 100644 index ff2bf025..00000000 --- a/docs/man/nng_ipc_dialer_free.3ipc.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= nng_ipc_dialer_free(3ipc) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_dialer_free - free IPC dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_ipc_dialer_free(nng_ipc_dialer *d); ----- - -== DESCRIPTION - -The `nng_ipc_dialer_free()` function closes the supplied IPC dialer _d_, -and frees the underlying resources associated with it. - -If any <> operations - using _d_ are -in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -WARNING: It is important that the application ensure that no further accesses -are made to _d_, as the memory backing it will be reclaimed for other uses. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_dialer_getopt.3ipc.adoc b/docs/man/nng_ipc_dialer_getopt.3ipc.adoc deleted file mode 100644 index 4a480bb5..00000000 --- a/docs/man/nng_ipc_dialer_getopt.3ipc.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= nng_ipc_dialer_getopt(3ipc) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_dialer_getopt - get option from IPC dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_ipc_getopt(nng_ipc_dialer *d, const char *name, void *data, size_t *sizep); ----- - -== DESCRIPTION - -The `nng_ipc_dialer_getopt()` is used to retrieve the value of the option _name_ for the <> _d_. -The size of the buffer located at _data_ to receive the copy is passed by the -caller at the location referenced by _sizep_. -If this size is sufficient to hold the entire object, the object is copied into -the buffer specified by _data_. -In either event, the size of the source object (the amount of data copied, -or that would have been copied if sufficient space were available) is stored -at the location of _sizep_. - -=== Options - -There are no predefined options for IPC dialers at this time. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The dialer is closed. -`NNG_EINVAL`:: There was insufficient space to receive the object. - The amount of data actually needed is returned in _sizep_. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EWRITEONLY`:: The option _name_ may not read. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_dialer_setopt.3ipc.adoc b/docs/man/nng_ipc_dialer_setopt.3ipc.adoc deleted file mode 100644 index 03f45023..00000000 --- a/docs/man/nng_ipc_dialer_setopt.3ipc.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nng_ipc_dialer_setopt(3ipc) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_dialer_setopt - set option on IPC dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_ipc_dialer_setopt(nng_ipc_dialer *d, const char *name, const void *data, size_t size); ----- - -== DESCRIPTION - -The `nng_ipc_dialer_setopt()` is used to set the option _name_ for the -<> _d_. -The value to set is copied from _data_, which should be _size_ bytes -in length. - -=== Options - -There are no predefined options for IPC dialers at this time. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The dialer is closed. -`NNG_EINVAL`:: Either _data_ or _size_ are invalid. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EREADONLY`:: The option _name_ may not be modified. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_free.3ipc.adoc b/docs/man/nng_ipc_free.3ipc.adoc deleted file mode 100644 index 646122a0..00000000 --- a/docs/man/nng_ipc_free.3ipc.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nng_ipc_free(3ipc) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_free - free IPC connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_ipc_free(nng_ipc *conn); ----- - -== DESCRIPTION - -The `nng_ipc_free()` function closes the supplied IPC connection, _conn_, -and frees the underlying resources associated with it. - -If any operations are pending (such as <> -or <>) they will be terminated with -an `NNG_ECLOSED` error condition. - -WARNING: It is important that the application ensure that no further accesses -are made to _conn_, as the memory backing it will be reclaimed for other uses. - -NOTE: 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. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_getopt.3ipc.adoc b/docs/man/nng_ipc_getopt.3ipc.adoc deleted file mode 100644 index d197e93e..00000000 --- a/docs/man/nng_ipc_getopt.3ipc.adoc +++ /dev/null @@ -1,70 +0,0 @@ -= nng_ipc_getopt(3ipc) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_getopt - get option from IPC connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_ipc_getopt(nng_ipc *conn, const char *name, void *data, size_t *sizep); ----- - -== DESCRIPTION - -The `nng_ipc_getopt()` is used to retrieve the value of the option _name_ for -the <> _conn_. -The size of the buffer located at _data_ to receive the copy is passed by the -caller at the location referenced by _sizep_. -If this size is sufficient to hold the entire object, the object is copied into -the buffer specified by _data_. -In either event, the size of the source object (the amount of data copied, -or that would have been copied if sufficient space were available) is stored -at the location of _sizep_. - -=== Options - -The options specifically suppported for retrieval from IPC connections are: - -* <> -* <> -* <> -* <> -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The connection _conn_ is closed. -`NNG_EINVAL`:: There was insufficient space to receive the object. - The amount of data actually needed is returned in _sizep_. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EWRITEONLY`:: The option _name_ may not read. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_listener.5.adoc b/docs/man/nng_ipc_listener.5.adoc deleted file mode 100644 index 1d748efc..00000000 --- a/docs/man/nng_ipc_listener.5.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_ipc_listener(5) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_listener - IPC listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_ipc_dialer_s nng_ipc_dialer; ----- - -== DESCRIPTION - -(((IPC, listener))) -An `nng_ipc_listener` is a handle to an IPC "`listener`", which is responsible -for accepting connections (<> objects) from remote -systems. - -NOTE: The `nng_ipc_listener` object is used for raw IPC connections, and -should not be confused with a listener object created using the -<> transport. - -TIP: Most NNG applications should not use this, but instead use the -<> transport instead. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_listener_accept.3ipc.adoc b/docs/man/nng_ipc_listener_accept.3ipc.adoc deleted file mode 100644 index 573539a8..00000000 --- a/docs/man/nng_ipc_listener_accept.3ipc.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= nng_ipc_listener_accept(3ipc) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_listener_accept - accept incoming IPC connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_ipc_listener_accept(nng_ipc_listener *l, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_ipc_listener_accept()` attempts to accept an incoming IPC connection -from a remote peer, using the listener _l_. -The operation is completed asynchronously, using _aio_. - -This operation can only be done after the listener is already bound to -an IPC path and is <>. - -If a connection is successfully established, the _aio_ will have the -resulting <> stored as its first output. -(See <>.) - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECLOSED`:: The listener is closed. -`NNG_ECONNRESET`:: The connection was reset by the peer. -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ESTATE`:: The listener is not not listening. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_listener_alloc.3ipc.adoc b/docs/man/nng_ipc_listener_alloc.3ipc.adoc deleted file mode 100644 index b9372bb7..00000000 --- a/docs/man/nng_ipc_listener_alloc.3ipc.adoc +++ /dev/null @@ -1,50 +0,0 @@ -= nng_ipc_listener_alloc(3ipc) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_listener_alloc - allocate IPC listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_ipc_listener_alloc(nng_ipc_listener *lp); ----- - -== DESCRIPTION - -The `nng_ipc_listener_alloc()` allocates an IPC listener, which can be used -to accept incoming connections over IPC, and stores a pointer to it -it in the location referenced by _lp_. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_listener_close.3ipc.adoc b/docs/man/nng_ipc_listener_close.3ipc.adoc deleted file mode 100644 index 8e27abde..00000000 --- a/docs/man/nng_ipc_listener_close.3ipc.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= nng_ipc_listener_close(3ipc) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_listener_close - close IPC listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_ipc_listener_close(nng_ipc_listener *l); ----- - -== DESCRIPTION - -The `nng_ipc_listener_close()` function closes the supplied IPC listener _l_, -but does not free the underlying resources associated with it. - -If any <> operations using _l_ -are in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -Furthermore any future accesses to the listener _l_ will also result in -`NNG_ECLOSED`. - -NOTE: This function does not release the memory for the listener, so the -application should still free the memory using -<> -once it is certain that nothing else is using it. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_listener_free.3ipc.adoc b/docs/man/nng_ipc_listener_free.3ipc.adoc deleted file mode 100644 index a90bcca5..00000000 --- a/docs/man/nng_ipc_listener_free.3ipc.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_ipc_listener_free(3ipc) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_listener_free - free IPC listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_ipc_listener_free(nng_ipc_listener *l); ----- - -== DESCRIPTION - -The `nng_ipc_listener_free()` function closes the supplied IPC listener _l_, -and frees the underlying resources associated with it. - -If any <> operations using _l_ -are in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -WARNING: It is important that the application ensure that no further accesses -are made to _l_, as the memory backing it will be reclaimed for other uses. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_listener_getopt.3ipc.adoc b/docs/man/nng_ipc_listener_getopt.3ipc.adoc deleted file mode 100644 index f5e47ede..00000000 --- a/docs/man/nng_ipc_listener_getopt.3ipc.adoc +++ /dev/null @@ -1,66 +0,0 @@ -= nng_ipc_listener_getopt(3ipc) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_listener_getopt - get option from IPC listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_ipc_listener_getopt(nng_ipc_listener *l, const char *name, void *data, size_t *sizep); ----- - -== DESCRIPTION - -The `nng_ipc_listener_getopt()` is used to retrieve the value of the option _name_ for the <> _l_. -The size of the buffer located at _data_ to receive the copy is passed by the -caller at the location referenced by _sizep_. -If this size is sufficient to hold the entire object, the object is copied into -the buffer specified by _data_. -In either event, the size of the source object (the amount of data copied, -or that would have been copied if sufficient space were available) is stored -at the location of _sizep_. - -=== Options - -The only option specifically suppported for retrieval from IPC listeners is: - -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The dialer is closed. -`NNG_EINVAL`:: There was insufficient space to receive the object. - The amount of data actually needed is returned in _sizep_. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EWRITEONLY`:: The option _name_ may not read. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_listener_listen.3ipc.adoc b/docs/man/nng_ipc_listener_listen.3ipc.adoc deleted file mode 100644 index 43b29c9b..00000000 --- a/docs/man/nng_ipc_listener_listen.3ipc.adoc +++ /dev/null @@ -1,56 +0,0 @@ -= nng_ipc_listener_listen(3ipc) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_listener_listen - bind IPC listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_ipc_listener_listen(nng_ipc_listener l, const nng_sockaddr *sa); ----- - -== DESCRIPTION - -The `nng_ipc_listener_listen()` attempts to bind the listener _l_ -to the local address specified by _sa_, which must be in the -`NNG_AF_IPC` address family and must have a valid IPC path. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EADDRINUSE`:: The address specified by _sa_ is already in use. -`NNG_EADDRINVAL`:: The address specified by _sa_ is invalid or unavailable. -`NNG_ECLOSED`:: The listener _l_ has been closed. -`NNG_EPERM`:: Insufficient permission to create the specified IPC path. -`NNG_ESTATE`:: The listener _l_ is already bound. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_listener_setopt.3ipc.adoc b/docs/man/nng_ipc_listener_setopt.3ipc.adoc deleted file mode 100644 index 0f627eab..00000000 --- a/docs/man/nng_ipc_listener_setopt.3ipc.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= nng_ipc_listener_setopt(3ipc) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_listener_setopt - set option on IPC listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_ipc_listener_setopt(nng_ipc_listener *l, const char *name, const void *data, size_t size); ----- - -== DESCRIPTION - -The `nng_ipc_listener_setopt()` is used to set the option _name_ for the -<> _l_. -The value to set is copied from _data_, which should be _size_ bytes -in length. - -=== Options - -The options specifically suppported for modification on IPC listeners are: - -* <> -* <> - -NOTE: Availability of the above options is platform-specific. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The listener is closed. -`NNG_EINVAL`:: Either _data_ or _size_ are invalid. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EREADONLY`:: The option _name_ may not be modified. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_recv.3ipc.adoc b/docs/man/nng_ipc_recv.3ipc.adoc deleted file mode 100644 index 44ed8651..00000000 --- a/docs/man/nng_ipc_recv.3ipc.adoc +++ /dev/null @@ -1,72 +0,0 @@ -= nng_ipc_recv(3ipc) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_recv - receive from IPC connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_ipc_recv(nng_ipc *conn, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_ipc_recv()` function starts an asynchronous receive from the -IPC connection _conn_, into the scatter/gather vector located in the -asynchronous I/O structure _aio_. - -NOTE: The <> function must have been -called first, to set the scatter/gather vector for _aio_. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, -and the final result may be obtained via -<>. -That result will either be zero or an error code. - -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 -<>. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_send.3ipc.adoc b/docs/man/nng_ipc_send.3ipc.adoc deleted file mode 100644 index d606ddd9..00000000 --- a/docs/man/nng_ipc_send.3ipc.adoc +++ /dev/null @@ -1,71 +0,0 @@ -= nng_ipc_send(3ipc) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_send - send to IPC connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_ipc_send(nng_ipc *conn, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_ipc_send()` function starts an asynchronous send over the -IPC connection _conn_ from the scatter/gather vector located in the -asynchronous I/O structure _aio_. - -NOTE: The <> function must have been -called first, to set the scatter/gather vector for _aio_. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, and the final -result may be obtained via <>. -That result will either be zero or an error code. - -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 -<>. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_ipc_setopt.3ipc.adoc b/docs/man/nng_ipc_setopt.3ipc.adoc deleted file mode 100644 index b22bda98..00000000 --- a/docs/man/nng_ipc_setopt.3ipc.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= nng_ipc_setopt(3ipc) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_setopt - set option on IPC connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_ipc_setopt(nng_ipc *conn, const char *name, const void *data, size_t size); ----- - -== DESCRIPTION - -The `nng_ipc_setopt()` is used to set the option _name_ for the -<> _conn_. -The value to set is copied from _data_, which should be _size_ bytes -in length. - -=== Options - -There are no options defined for modification on IPC connections at this time. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The connection _conn_ is closed. -`NNG_EINVAL`:: Either _data_ or _size_ are invalid. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EREADONLY`:: The option _name_ may not be modified. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_stream.5.adoc b/docs/man/nng_stream.5.adoc new file mode 100644 index 00000000..3e815da4 --- /dev/null +++ b/docs/man/nng_stream.5.adoc @@ -0,0 +1,80 @@ += nng_stream(5) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream - byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct nng_stream nng_stream; +---- + +== DESCRIPTION + +An `nng_stream` (((byte stream))) represents a byte stream. +This may correspond to an underlying connection such a TCP connection or +a connected UNIX domain socket or named pipe. + +NOTE: The `nng_stream` object is used for raw byte stream connections, and +should not be confused with a pipe object created on +xref:nng_socket.5.adoc[socket] using the +xref:nng_listen.3.adoc[`nng_listen()`], +xref:nng_dial.3.adoc[`nng_dial()`] or related functions. + +These objects are created either establishing an outgoing connection +with +xref:nng_stream_dialer_dial.3str.adoc[`nng_stream_dialer_dial()`] +or by accepting in incoming connection with +xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`]. + +Byte streams are "`reliable`" in that data +will not be delivered out of order, or with portions missing. + +Data can be sent using +xref:nng_stream_send.3str.adoc[`nng_stream_send()`] or +received with +xref:nng_stream_recv.3str.adoc[`nng_stream_recv()`]. + +When the connection is no longer needed, it should be freed with +xref:nng_stream_free.3str.adoc[`nng_stream_free()`]. + +TIP: It is possible to close the connection, without freeing it, by +using +xref:nng_stream_close.3str.adoc[`nng_stream_close()`]. + +Byte streams may, depending on the underlying technology, +support various +xref:nng_options.5.adoc[options], which +can be accessed using the +xref:nng_stream_get.3str.adoc[`nng_stream_get()`] and +xref:nng_stream_set.3str.adoc[`nng_stream_set()`] family of +functions. + +== SEE ALSO + +[.text-left] +xref:libnng.3.adoc[libnng(3)], +xref:nng_stream_close.3str.adoc[nng_stream_close(3str)], +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], +xref:nng_stream_free.3str.adoc[nng_stream_free(3str)], +xref:nng_stream_getopt.3str.adoc[nng_stream_getopt(3str)], +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], +xref:nng_stream_recv.3str.adoc[nng_stream_recv(3str)], +xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], +xref:nng_stream_setopt.3str.adoc[nng_stream_setopt(3str)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng.7.adoc[nng(7)], diff --git a/docs/man/nng_stream_close.3str.adoc b/docs/man/nng_stream_close.3str.adoc new file mode 100644 index 00000000..9e7b8d6a --- /dev/null +++ b/docs/man/nng_stream_close.3str.adoc @@ -0,0 +1,65 @@ += nng_stream_close(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_close - close byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_close(nng_stream *s); +---- + +== DESCRIPTION + +The `nng_stream_close()` function closes the +xref:nng_stream.5.adoc[byte stream] _s_. + +If any operations are pending, such as +xref:nng_stream_send.3str.adoc[`nng_stream_send()`] +or +xref:nng_stream_recv.3str.adoc[`nng_stream_recv()`], +they will be terminated with +an `NNG_ECLOSED` error condition. +Also, any new operations will fail with `NNG_ECLOSED` after the connection +is closed. + +NOTE: 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. + +NOTE: 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 +xref:nng_stream_free.3str.adoc[`nng_stream_free()`]. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_free.3str.adoc[nng_stream_free(3str)], +xref:nng_stream_recv.3str.adoc[nng_stream_recv(3str)], +xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/man/nng_stream_dialer.5.adoc b/docs/man/nng_stream_dialer.5.adoc new file mode 100644 index 00000000..5c1d2e0b --- /dev/null +++ b/docs/man/nng_stream_dialer.5.adoc @@ -0,0 +1,46 @@ += nng_stream_dialer(5) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer - byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct nng_stream_dialer nng_stream_dialer; +---- + +== DESCRIPTION + +(((byte stream, dialer))) +An `nng_stream_dialer` is a handle to a "`dialer`" for byte streams, +and is responsible for creating +xref:nng_stream.5.adoc[`nng_stream`] objects (corresponding to connected byte +streams) by connecting to remote peers. + +NOTE: The `nng_stream_dialer` object is used for low-level byte stream +connections, and should not be confused with a high-level +xref:nng_dialer.5.adoc[`nng_dialer`] object. + +== SEE ALSO + +[.text-left] +xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], +xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)], +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], +xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)], +xref:nng_stream.5.adoc[nng_stream(5)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_dialer_alloc.3str.adoc b/docs/man/nng_stream_dialer_alloc.3str.adoc new file mode 100644 index 00000000..0c2db67c --- /dev/null +++ b/docs/man/nng_stream_dialer_alloc.3str.adoc @@ -0,0 +1,68 @@ += nng_stream_dialer_alloc(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer_alloc - allocate byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_dialer_alloc(nng_stream_dialer **dp, const char *addr); + +int nng_stream_dialer_alloc_url(nng_stream_dialer **dp, const nng_url *url); +---- + +== DESCRIPTION + +These functions allocates a dialer for byte streams. +Dialers create +xref:nng_stream.5.adoc[`nng_stream`] objects by initiating outgoing +connections, via the +xref:nng_stream_dialer_dial.3str.adoc[`nng_stream_dialer_dial()`] function. + +The first form, `nng_stream_dialer_alloc()`, connects to the address +specified by _addr_, which should be a string representing a URL. + +The second form, `nng_stream_dialer_alloc_url()`, takes a pre-parsed +or pre-constructed +xref:nng_url.5.adoc[`nng_url`] object to determine the remote address. + +These functions may support different URL schemes, such as +`ipc://`, `tcp://`, `tls+tcp://`, or `ws://`. + +Both forms store the dialer in the location referenced by _dp_. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: The URL scheme is not supported by the implementation. +`NNG_EADDRINVAL`:: The URL requested is invalid. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)] +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)] +xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)] +xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get(3str)] +xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set(3str)] +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/man/nng_stream_dialer_close.3str.adoc b/docs/man/nng_stream_dialer_close.3str.adoc new file mode 100644 index 00000000..59d9dec0 --- /dev/null +++ b/docs/man/nng_stream_dialer_close.3str.adoc @@ -0,0 +1,60 @@ += nng_stream_dialer_close(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer_close - close byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_dialer_close(nng_stream_dialer *d); +---- + +== DESCRIPTION + +The `nng_stream_dialer_close()` function closes the supplied byte stream +dialer _d_, +but does not free the underlying resources associated with it. + +If any +xref:nng_stream_dialer_dial.3str.adoc[dial] +operations using _d_ are +in progress, they will be terminated with an `NNG_ECLOSED` error condition. + +Furthermore any future accesses to the dialer _d_ will also result in +`NNG_ECLOSED`. + +NOTE: This function does not release the memory for the dialer, so the +application should still free the memory using +xref:nng_stream_dialer_free.3str.adoc[`nng_stream_dialer_free()`] +once it is certain that nothing else is using it. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], +xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/man/nng_stream_dialer_dial.3str.adoc b/docs/man/nng_stream_dialer_dial.3str.adoc new file mode 100644 index 00000000..cc4c55de --- /dev/null +++ b/docs/man/nng_stream_dialer_dial.3str.adoc @@ -0,0 +1,65 @@ += nng_stream_dialer_dial(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer_dial - initiate outgoing byte stream connection + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_dialer_dial(nng_stream_dialer *d, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_stream_dialer_dial()` attempts to establish a connection to the +remote peer for the dialer _d_. +The operation is completed asynchronously, using _aio_. + +TIP: The peer address is determined by the address specified using +xref:nng_stream_dialer_alloc.3str.adoc[`nng_stream_dialer_alloc()`] or +xref:nng_stream_dialer_alloc_url.3str.adoc[`nng_stream_dialer_alloc_url()`]. + +If a connection is successfully established, the _aio_ will have the +resulting +xref:nng_stream.5.adoc[`nng_stream`] object stored as its first output. +(See +xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`].) + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_EADDRINVAL`:: The address specified is invalid. +`NNG_ECANCELED`:: The operation was aborted. +`NNG_ECLOSED`:: The dialer is closed. +`NNG_ECONNREFUSED`:: The connection was refused by the server. +`NNG_ECONNRESET`:: The connection was reset by the server. +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], +xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)], +xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng_stream.5.adoc[nng_stream(5)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/man/nng_stream_dialer_free.3str.adoc b/docs/man/nng_stream_dialer_free.3str.adoc new file mode 100644 index 00000000..6669ca1e --- /dev/null +++ b/docs/man/nng_stream_dialer_free.3str.adoc @@ -0,0 +1,54 @@ += nng_stream_dialer_free(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions + +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer_free - free byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_dialer_free(nng_stream_dialer *d); +---- + +== DESCRIPTION + +The `nng_stream_dialer_free()` function closes the supplied +byte stream dialer _d_, +and frees the underlying resources associated with it. + +If any +xref:nng_stream_dialer_dial.3str.adoc[dial] operations using _d_ are +in progress, they will be terminated with an `NNG_ECLOSED` error condition. + +WARNING: It is important that the application ensure that no further accesses +are made to _d_, as the memory backing it will be reclaimed for other uses. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], +xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)], +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/man/nng_stream_dialer_get.3str.adoc b/docs/man/nng_stream_dialer_get.3str.adoc new file mode 100644 index 00000000..b7043c74 --- /dev/null +++ b/docs/man/nng_stream_dialer_get.3str.adoc @@ -0,0 +1,143 @@ += nng_stream_dialer_get(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer_get - get option from byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_dialer_get(nng_stream_dialer *d, const char *opt, void *val, size_t *sizep); + +int nng_stream_dialer_get_bool(nng_stream_dialer *d, const char *opt, bool *valp); + +int nng_stream_dialer_get_int(nng_stream_dialer *d, const char *opt, int *valp); + +int nng_stream_dialer_get_ms(nng_stream_dialer *d, const char *opt, nng_duration *valp); + +int nng_stream_dialer_get_ptr(nng_stream_dialer *d, const char *opt, void **valp); + +int nng_stream_dialer_get_size(nng_stream_dialer *d, const char *opt, size_t *valp); + +int nng_stream_dialer_get_addr(nng_stream_dialer *d, const char *opt, nng_sockaddr *valp); + +int nng_stream_dialer_get_string(nng_stream_dialer *d, const char *opt, char **valp); + +int nng_stream_dialer_get_uint64(nng_stream_dialer *d, const char *opt, uint64_t *valp); +---- + +== DESCRIPTION + + +The `nng_stream_dialer_get()` functions are used to retrieve option values for the +xref:nng_stream_dialer.5.adoc[byte stream dialer] _d_. + +The actual options that may be retrieved in this way vary. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the connected +byte stream dialer _d_. +The forms vary based on the type of the option they take. + +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. + +`nng_stream_dialer_get()`:: +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 _val_, +and the size of the buffer shall be stored at the location referenced by +_sizep_. ++ +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 _sizep_. +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 _sizep_ does not exceed the original buffer size. ++ +It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_dialer_get_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_dialer_get_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_dialer_get_ms()`:: +This function is used to retrieve time +xref:nng_duration.5.adoc[durations] +(such as timeouts), stored as a number of milliseconds. +(The special value ((`NNG_DUR_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DUR_DEFAULT`)) means a context-specific default.) + +`nng_stream_dialer_get_ptr()`:: +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 *pointer* to the object is copied. ++ +NOTE: 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. + +`nng_stream_dialer_get_size()`:: +This function is used to retrieve a size, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_stream_dialer_get_addr()`:: +This function is used to retrieve a +xref:nng_sockaddr.5.adoc[socket address]. + +`nng_stream_dialer_get_string()`:: +This function is used to retrieve a `NULL`-terminated string. +This string is created from the source using +xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_stream_dialer_get_uint64()`:: +This function is used to retrieve a 64-bit unsigned value. +This is typically used for identifiers, network +numbers, and similar options. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The dialer is closed. +`NNG_EINVAL`:: There was insufficient space to receive the object. + The amount of data actually needed is returned in _sizep_. +`NNG_ENOTSUP`:: The option is not supported. +`NNG_EWRITEONLY`:: The option may not read. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set(3str)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/man/nng_stream_dialer_set.3str.adoc b/docs/man/nng_stream_dialer_set.3str.adoc new file mode 100644 index 00000000..1a1b6862 --- /dev/null +++ b/docs/man/nng_stream_dialer_set.3str.adoc @@ -0,0 +1,133 @@ += nng_stream_dialer_set(3str) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer_set - set option on byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_dialer_set(nng_stream_dialer *d, const char *name, const void *data, size_t size); + +int nng_stream_dialer_set_bool(nng_stream_dialer *d, const char *opt, int val); + +int nng_stream_dialer_set_int(nng_stream_dialer *d, const char *opt, int val); + +int nng_stream_dialer_set_ms(nng_stream_dialer *d, const char *opt, nng_duration val); + +int nng_stream_dialer_set_ptr(nng_stream_dialer *d, const char *opt, void *val); + +int nng_stream_dialer_set_size(nng_stream_dialer *d, const char *opt, size_t val); + +int nng_stream_dialer_set_string(nng_stream_dialer *d, const char *opt, const char *val); + +int nng_stream_dialer_set_uint64(nng_stream_dialer *d, const char *opt, uint64_t val); + +int nng_stream_dialer_set_addr(nng_stream_dialer *d, const char *opt, const nng_sockaddr *val); + +---- + +== DESCRIPTION + +The `nng_stream_dialer_set()` functions are used to configure options for the +xref:nng_stream.5.adoc[byte stream dialer] _d_. +The actual options that may be configured in this way vary, and are +specified by _opt_. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific and protocol-specific options are +documented with the transports and protocols themselves. + +=== Forms + +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. + +`nng_stream_dialer_set()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _size_ is the +size of the objected located at _val_. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_dialer_set_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_dialer_set_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_dialer_set_ms()`:: +This function is used to configure time durations (such as timeouts) using +the type +xref:nng_duration.5.adoc[`nng_duration`]. +The duration is an integer number of milliseconds. + +`nng_stream_dialer_set_ptr()`:: +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 +xref:nng_tls_config.3tls.adoc[`nng_tls_config_alloc()`] +can be passed this way. ++ +NOTE: This form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. +Please see the documentation for the specific option for further details. + +`nng_stream_dialer_set_size()`:: +This function is used to configure a size, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_stream_dialer_set_string()`:: +This function is used to pass configure a string. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. +(Other constraints may apply as well, see the documentation for each option +for details.) + +`nng_stream_dialer_set_uint64()`:: +This function is used to configure a 64-bit unsigned value/ +This is typically used for identifiers, network numbers, +and similar options. + +`nng_stream_dialer_set_addr()`:: +This function is used to configure a +xref:nng_sockaddr.5.adoc[socket address]. +The value is copied, and thus the caller may discard the supplied +value immediately after this function returns. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The dialer is closed. +`NNG_EINVAL`:: Either _data_ or _size_ are invalid. +`NNG_ENOTSUP`:: The option is not supported. +`NNG_EREADONLY`:: The option may not be modified. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get(3str)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_ipc_options.5.adoc[nng_ipc_options(5)], +xref:nng_tcp_options.5.adoc[nng_tcp_options(5)], +xref:nng_tls_options.5.adoc[nng_tls_options(5)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] \ No newline at end of file diff --git a/docs/man/nng_stream_free.3str.adoc b/docs/man/nng_stream_free.3str.adoc new file mode 100644 index 00000000..30679458 --- /dev/null +++ b/docs/man/nng_stream_free.3str.adoc @@ -0,0 +1,61 @@ += nng_stream_free(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_free - free byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_free(nng_stream *s); +---- + +== DESCRIPTION + +The `nng_stream_free()` function closes the +xref:nng_stream.5.adoc[byte stream] _s_, +and frees the underlying resources associated with it. + +If any operations are pending, such as +xref:nng_stream_send.3str.adoc[`nng_stream_send()`] +or +xref:nng_stream_recv.3str.adoc[`nng_stream_recv()`], +they will be terminated with an `NNG_ECLOSED` error condition. + +WARNING: It is important that the application ensure that no further accesses +are made to _s_, as the memory backing it will be reclaimed for other uses. + +NOTE: 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. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_close.3str.adoc[nng_stream_close(3str)], +xref:nng_stream_recv.3str.adoc[nng_stream_recv(3str)], +xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/man/nng_stream_get.3str.adoc b/docs/man/nng_stream_get.3str.adoc new file mode 100644 index 00000000..9a2b0220 --- /dev/null +++ b/docs/man/nng_stream_get.3str.adoc @@ -0,0 +1,146 @@ += nng_stream_get(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_get - get option from byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_get(nng_stream *s, const char *opt, void *val, size_t *sizep); + +int nng_stream_get_bool(nng_stream *s, const char *opt, bool *valp); + +int nng_stream_get_int(nng_stream *s, const char *opt, int *valp); + +int nng_stream_get_ms(nng_stream *s, const char *opt, nng_duration *valp); + +int nng_stream_get_ptr(nng_stream *s, const char *opt, void **valp); + +int nng_stream_get_size(nng_stream *s, const char *opt, size_t *valp); + +int nng_stream_get_addr(nng_stream *s, const char *opt, nng_sockaddr *valp); + +int nng_stream_get_string(nng_stream *s, const char *opt, char **valp); + +int nng_stream_get_uint64(nng_stream *s, const char *opt, uint64_t *valp); + +---- + +== DESCRIPTION + +The `nng_stream_get()` functions are used to retrieve option values for the +xref:nng_stream.5.adoc[byte stream] _conn_. + +The actual options that may be retrieved in this way vary. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the connected +byte stream _s_. +The forms vary based on the type of the option they take. + +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. + +`nng_stream_get()`:: +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 _val_, +and the size of the buffer shall be stored at the location referenced by +_sizep_. ++ +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 _sizep_. +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 _sizep_ does not exceed the original buffer size. ++ +It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_get_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_get_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_get_ms()`:: +This function is used to retrieve time +xref:nng_duration.5.adoc[durations] +(such as timeouts), stored as a number of milliseconds. +(The special value ((`NNG_DUR_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DUR_DEFAULT`)) means a context-specific default.) + +`nng_stream_get_ptr()`:: +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 *pointer* to the object is copied. ++ +NOTE: 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. + +`nng_stream_get_size()`:: +This function is used to retrieve a size, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_stream_get_addr()`:: +This function is used to retrieve a +xref:nng_sockaddr.5.adoc[socket address]. + +`nng_stream_get_string()`:: +This function is used to retrieve a `NULL`-terminated string. +This string is created from the source using +xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_stream_get_uint64()`:: +This function is used to retrieve a 64-bit unsigned value. +This is typically used for identifiers, network +numbers, and similar options. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The connection is closed. +`NNG_EINVAL`:: There was insufficient space to receive the object. + The amount of data actually needed is returned in _sizep_. +`NNG_ENOTSUP`:: The option is not supported. +`NNG_EWRITEONLY`:: The option may not read. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_set.3str.adoc[nng_stream_set(3str)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_ipc_options.5.adoc[nng_ipc_options(5)], +xref:nng_tcp_options.5.adoc[nng_tcp_options(5)], +xref:nng_tls_options.5.adoc[nng_tls_options(5)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/man/nng_stream_listener.5.adoc b/docs/man/nng_stream_listener.5.adoc new file mode 100644 index 00000000..c8966326 --- /dev/null +++ b/docs/man/nng_stream_listener.5.adoc @@ -0,0 +1,48 @@ += nng_stream_listener(5) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener - byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct nng_stream_dialer nng_stream_dialer; +---- + +== DESCRIPTION + +(((IPC, listener))) +An `nng_stream_listener` is a handle to a byte stream "`listener`", +which is responsible for accepting incoming connections and creating +corresponding +xref:nng_stream.5.adoc[`nng_stream`] from them. + +NOTE: The `nng_stream_listener` object is a low-level object for +raw byte stream connections, +and should not be confused with a high-level +xref:nng_listener.5.adoc[`nng_listener`] object. + +== SEE ALSO + +[.text-left] +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], +xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], +xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)], +xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)], +xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)], +xref:nng_stream.5.adoc[nng_stream(5)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/man/nng_stream_listener_accept.3str.adoc b/docs/man/nng_stream_listener_accept.3str.adoc new file mode 100644 index 00000000..f5ffbca5 --- /dev/null +++ b/docs/man/nng_stream_listener_accept.3str.adoc @@ -0,0 +1,64 @@ += nng_stream_listener_accept(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_accept - accept incoming byte stream connection + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_listener_accept(nng_stream_listener *l, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_stream_listener_accept()` attempts to accept an incoming byte stream +connection from a remote peer, using the listener _l_. +The operation is completed asynchronously, using _aio_. + +This operation can only be done after the listener is already +xref:nng_stream_listener_listen.3str.adoc[listening]. + +If a connection is successfully established, the _aio_ will have the +resulting +xref:nng_stream.5.adoc[`nng_stream`] object stored as its first output, +which can be retrieved with +xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`]. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was aborted. +`NNG_ECLOSED`:: The listener is closed. +`NNG_ECONNRESET`:: The connection was reset by the peer. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ESTATE`:: The listener is not not listening. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], +xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)], +xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)], +xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng_stream.5.adoc[nng_stream(5)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_listener_alloc.3str.adoc b/docs/man/nng_stream_listener_alloc.3str.adoc new file mode 100644 index 00000000..966866ba --- /dev/null +++ b/docs/man/nng_stream_listener_alloc.3str.adoc @@ -0,0 +1,70 @@ += nng_stream_listener_alloc(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_alloc - allocate byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_listener_alloc(nng_stream_listener **lp, const char *addr); + +int nng_stream_listener_alloc_url(nng_stream_listener **lp, const nng_url *url); +---- + +== DESCRIPTION + +These functions allocates a listener for byte streams. +Listeners create +xref:nng_stream.5.adoc[`nng_stream`] objects by accepting incoming +connections, via the +xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`] +function. + +The first form, `nng_stream_listener_alloc()`, connects to the address +specified by _addr_, which should be a string representing a URL. + +The second form, `nng_stream_listener_alloc_url()`, takes a pre-parsed +or pre-constructed +xref:nng_url.5.adoc[`nng_url`] object to determine the remote address. + +These functions may support different URL schemes, such as +`ipc://`, `tcp://`, `tls+tcp://`, or `ws://`. + +Both forms store the listener in the location referenced by _lp_. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: The URL scheme is not supported by the implementation. +`NNG_EADDRINVAL`:: The URL requested is invalid. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)] +xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)] +xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)] +xref:nng_stream_listener_get.3str.adoc[nng_stream_listener_get(3str)] +xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)] +xref:nng_stream_listener_set.3str.adoc[nng_stream_listener_set(3str)] +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_listener_close.3str.adoc b/docs/man/nng_stream_listener_close.3str.adoc new file mode 100644 index 00000000..a810509e --- /dev/null +++ b/docs/man/nng_stream_listener_close.3str.adoc @@ -0,0 +1,60 @@ += nng_stream_listener_close(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_close - close byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_listener_close(nng_stream_listener *l); +---- + +== DESCRIPTION + +The `nng_stream_listener_close()` function closes the supplied connected byte +stream listener _l_, +but does not free the underlying resources associated with it. + +If any +xref:nng_stream_listener_accept.3str.adoc[accept] +operations using _d_ are +in progress, they will be terminated with an `NNG_ECLOSED` error condition. + +Furthermore any future accesses to the listener _l_ will also result in +`NNG_ECLOSED`. + +NOTE: This function does not release the memory for the listener, so the +application should still free the memory using +xref:nng_stream_listener_free.3str.adoc[`nng_stream_listener_free()`] +once it is certain that nothing else is using it. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], +xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], +xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_listener_free.3str.adoc b/docs/man/nng_stream_listener_free.3str.adoc new file mode 100644 index 00000000..aecd8895 --- /dev/null +++ b/docs/man/nng_stream_listener_free.3str.adoc @@ -0,0 +1,54 @@ += nng_stream_listener_free(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions + +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_free - free byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_listener_free(nng_stream_listener *)l; +---- + +== DESCRIPTION + +The `nng_stream_listener_free()` function closes the supplied +byte stream listener _l_, +and frees the underlying resources associated with it. + +If any +xref:nng_stream_listener_accept.3str.adoc[accept] operations using __l are +in progress, they will be terminated with an `NNG_ECLOSED` error condition. + +WARNING: It is important that the application ensure that no further accesses +are made to _l_, as the memory backing it will be reclaimed for other uses. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], +xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], +xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_listener_get.3str.adoc b/docs/man/nng_stream_listener_get.3str.adoc new file mode 100644 index 00000000..87c25158 --- /dev/null +++ b/docs/man/nng_stream_listener_get.3str.adoc @@ -0,0 +1,144 @@ += nng_stream_listener_get(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_get - get option from byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_listener_get(nng_stream_listener *l, const char *opt, void *val, size_t *sizep); + +int nng_stream_listener_get_bool(nng_stream_listener *l, const char *opt, bool *valp); + +int nng_stream_listener_get_int(nng_stream_listener *l, const char *opt, int *valp); + +int nng_stream_listener_get_ms(nng_stream_listener *l, const char *opt, nng_duration *valp); + +int nng_stream_listener_get_ptr(nng_stream_listener *l, const char *opt, void **valp); + +int nng_stream_listener_get_size(nng_stream_listener *l, const char *opt, size_t *valp); + +int nng_stream_listener_get_addr(nng_stream_listener *l, const char *opt, nng_sockaddr *valp); + +int nng_stream_listener_get_string(nng_stream_listener *l, const char *opt, char **valp); + +int nng_stream_listener_get_uint64(nng_stream_listener *l, const char *opt, uint64_t *valp); +---- + +== DESCRIPTION + + +The `nng_stream_listener_get()` functions are used to retrieve option values +for the +xref:nng_stream_listener.5.adoc[byte stream listener] _l_. + +The actual options that may be retrieved in this way vary. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the connected +byte stream listener _l_. +The forms vary based on the type of the option they take. + +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. + +`nng_stream_listener_get()`:: +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 _val_, +and the size of the buffer shall be stored at the location referenced by +_sizep_. ++ +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 _sizep_. +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 _sizep_ does not exceed the original buffer size. ++ +It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_listener_get_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_listener_get_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_listener_get_ms()`:: +This function is used to retrieve time +xref:nng_duration.5.adoc[durations] +(such as timeouts), stored as a number of milliseconds. +(The special value ((`NNG_DUR_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DUR_DEFAULT`)) means a context-specific default.) + +`nng_stream_listener_get_ptr()`:: +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 *pointer* to the object is copied. ++ +NOTE: 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. + +`nng_stream_listener_get_size()`:: +This function is used to retrieve a size, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_stream_listener_get_addr()`:: +This function is used to retrieve a +xref:nng_sockaddr.5.adoc[socket address]. + +`nng_stream_listener_get_string()`:: +This function is used to retrieve a `NULL`-terminated string. +This string is created from the source using +xref:nng_strdup.3.adoc[`nng_strdup()`] +and consequently must be freed by the caller using +xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. + +`nng_stream_listener_get_uint64()`:: +This function is used to retrieve a 64-bit unsigned value. +This is typically used for identifiers, network +numbers, and similar options. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The listener is closed. +`NNG_EINVAL`:: There was insufficient space to receive the object. + The amount of data actually needed is returned in _sizep_. +`NNG_ENOTSUP`:: The option is not supported. +`NNG_EWRITEONLY`:: The option may not read. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_set.3str.adoc[nng_stream_listener_set(3str)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_listener_listen.3str.adoc b/docs/man/nng_stream_listener_listen.3str.adoc new file mode 100644 index 00000000..e8473b52 --- /dev/null +++ b/docs/man/nng_stream_listener_listen.3str.adoc @@ -0,0 +1,66 @@ += nng_stream_listener_listen(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_listen - bind listener to configured address + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_listener_listen(nng_stream_listener *l); +---- + +== DESCRIPTION + +The `nng_stream_listener_listen()` attempts to bind the listener _l_ +to the local address specified when the listener was created. + +This must generally be done before accepting incoming connections using +xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`]. + +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. + +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 +xref:nng_stream_listener_get.3str.adoc[`nng_stream_listener_get()`], +typically with the +xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`] option. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EADDRINUSE`:: The address is already in use. +`NNG_EADDRINVAL`:: The address is invalid or unavailable. +`NNG_ECLOSED`:: The listener has been closed. +`NNG_ESTATE`:: The listener is already bound. + +== SEE ALSO + +[.text-left] +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_listener_set.3str.adoc b/docs/man/nng_stream_listener_set.3str.adoc new file mode 100644 index 00000000..4fd47d4f --- /dev/null +++ b/docs/man/nng_stream_listener_set.3str.adoc @@ -0,0 +1,133 @@ += nng_stream_listener_set(3str) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_set - set option on byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_listener_set(nng_stream_listener *l, const char *name, const void *data, size_t size); + +int nng_stream_listener_set_bool(nng_stream_listener *l, const char *opt, int val); + +int nng_stream_listener_set_int(nng_stream_listener *l, const char *opt, int val); + +int nng_stream_listener_set_ms(nng_stream_listener *l, const char *opt, nng_duration val); + +int nng_stream_listener_set_ptr(nng_stream_listener *l, const char *opt, void *val); + +int nng_stream_listener_set_size(nng_stream_listener *l, const char *opt, size_t val); + +int nng_stream_listener_set_string(nng_stream_listener *l, const char *opt, const char *val); + +int nng_stream_listener_set_uint64(nng_stream_listener *l, const char *opt, uint64_t val); + +int nng_stream_listener_set_addr(nng_stream_listener *l, const char *opt, const nng_sockaddr *val); + +---- + +== DESCRIPTION + +The `nng_stream_listener_set()` functions are used to configure options for the +xref:nng_stream.5.adoc[byte stream listener] _l_. +The actual options that may be configured in this way vary, and are +specified by _opt_. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific and protocol-specific options are +documented with the transports and protocols themselves. + +=== Forms + +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. + +`nng_stream_listener_set()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _size_ is the +size of the objected located at _val_. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_listener_set_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_listener_set_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_listener_set_ms()`:: +This function is used to configure time durations (such as timeouts) using +the type +xref:nng_duration.5.adoc[`nng_duration`]. +The duration is an integer number of milliseconds. + +`nng_stream_listener_set_ptr()`:: +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 +xref:nng_tls_config.3tls.adoc[`nng_tls_config_alloc()`] +can be passed this way. ++ +NOTE: This form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. +Please see the documentation for the specific option for further details. + +`nng_stream_listener_set_size()`:: +This function is used to configure a size, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_stream_listener_set_string()`:: +This function is used to pass configure a string. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. +(Other constraints may apply as well, see the documentation for each option +for details.) + +`nng_stream_listener_set_uint64()`:: +This function is used to configure a 64-bit unsigned value/ +This is typically used for identifiers, network numbers, +and similar options. + +`nng_stream_listener_set_addr()`:: +This function is used to configure a +xref:nng_sockaddr.5.adoc[socket address]. +The value is copied, and thus the caller may discard the supplied +value immediately after this function returns. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The listener is closed. +`NNG_EINVAL`:: Either _data_ or _size_ are invalid. +`NNG_ENOTSUP`:: The option is not supported. +`NNG_EREADONLY`:: The option may not be modified. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_get.3str.adoc[nng_stream_listener_get(3str)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_ipc_options.5.adoc[nng_ipc_options(5)], +xref:nng_tcp_options.5.adoc[nng_tcp_options(5)], +xref:nng_tls_options.5.adoc[nng_tls_options(5)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] \ No newline at end of file diff --git a/docs/man/nng_stream_recv.3str.adoc b/docs/man/nng_stream_recv.3str.adoc new file mode 100644 index 00000000..3acb1921 --- /dev/null +++ b/docs/man/nng_stream_recv.3str.adoc @@ -0,0 +1,73 @@ += nng_stream_send(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_send - receive from byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_send(nng_stream *s, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_stream_send()` function starts an asynchronous receive from the +xref:nng_stream.5.adoc[byte stream] _s_ +into the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The +xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. +Completion of the operation is signaled via the _aio_, +and the final result may be obtained via +xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +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 +xref:nng_aio_count.3.adoc[`nng_aio_count()`]. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_close.3str.adoc[nng_stream_close(3str)], +xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/man/nng_stream_send.3str.adoc b/docs/man/nng_stream_send.3str.adoc new file mode 100644 index 00000000..2ae7355a --- /dev/null +++ b/docs/man/nng_stream_send.3str.adoc @@ -0,0 +1,74 @@ += nng_stream_send(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_send - send to byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_send(nng_stream *s, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_stream_send()` function starts an asynchronous send over the +xref:nng_stream.5.adoc[byte stream] _s_ +from the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The +xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] +function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. +Completion of the operation is signaled via the _aio_, and the final +result may be obtained via +xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +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 +xref:nng_aio_count.3.adoc[`nng_aio_count()`]. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_close.3str.adoc#[nng_stream_close(3str)], +xref:nng_stream_recv.3str.adoc#[nng_stream_recv(3str)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/man/nng_stream_set.3str.adoc b/docs/man/nng_stream_set.3str.adoc new file mode 100644 index 00000000..cc6d4610 --- /dev/null +++ b/docs/man/nng_stream_set.3str.adoc @@ -0,0 +1,133 @@ += nng_stream_set(3str) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_set - set option on byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_set(nng_stream *s, const char *name, const void *data, size_t size); + +int nng_stream_set_bool(nng_stream *s, const char *opt, int val); + +int nng_stream_set_int(nng_stream *s, const char *opt, int val); + +int nng_stream_set_ms(nng_stream *s, const char *opt, nng_duration val); + +int nng_stream_set_ptr(nng_stream *s, const char *opt, void *val); + +int nng_stream_set_size(nng_stream *s, const char *opt, size_t val); + +int nng_stream_set_string(nng_stream *s, const char *opt, const char *val); + +int nng_stream_set_uint64(nng_stream *s, const char *opt, uint64_t val); + +int nng_stream_set_addr(nng_stream *s, const char *opt, const nng_sockaddr *val); + +---- + +== DESCRIPTION + +The `nng_stream_set()` functions are used to configure options for the +xref:nng_stream.5.adoc[byte stream] _s_. +The actual options that may be configured in this way vary, and are +specified by _opt_. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific and protocol-specific options are +documented with the transports and protocols themselves. + +=== Forms + +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. + +`nng_stream_set()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _size_ is the +size of the objected located at _val_. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_set_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_set_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_set_ms()`:: +This function is used to configure time durations (such as timeouts) using +the type +xref:nng_duration.5.adoc[`nng_duration`]. +The duration is an integer number of milliseconds. + +`nng_stream_set_ptr()`:: +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 +xref:nng_tls_config.3tls.adoc[`nng_tls_config_alloc()`] +can be passed this way. ++ +NOTE: This form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. +Please see the documentation for the specific option for further details. + +`nng_stream_set_size()`:: +This function is used to configure a size, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_stream_set_string()`:: +This function is used to pass configure a string. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. +(Other constraints may apply as well, see the documentation for each option +for details.) + +`nng_stream_set_uint64()`:: +This function is used to configure a 64-bit unsigned value/ +This is typically used for identifiers, network numbers, +and similar options. + +`nng_stream_set_addr()`:: +This function is used to configure a +xref:nng_sockaddr.5.adoc[socket address]. +The value is copied, and thus the caller may discard the supplied +value immediately after this function returns. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: The connection is closed. +`NNG_EINVAL`:: Either _data_ or _size_ are invalid. +`NNG_ENOTSUP`:: The option is not supported. +`NNG_EREADONLY`:: The option may not be modified. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_get.3str.adoc[nng_stream_get(3str)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_ipc_options.5.adoc[nng_ipc_options(5)], +xref:nng_tcp_options.5.adoc[nng_tcp_options(5)], +xref:nng_tls_options.5.adoc[nng_tls_options(5)], +xref:nng_stream.5.adoc[nng_stream(5)] \ No newline at end of file diff --git a/docs/man/nng_tcp_close.3tcp.adoc b/docs/man/nng_tcp_close.3tcp.adoc deleted file mode 100644 index 5e68398b..00000000 --- a/docs/man/nng_tcp_close.3tcp.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_tcp_close(3tcp) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_close - close TCP connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tcp_close(nng_tcp *conn); ----- - -== DESCRIPTION - -The `nng_tcp_close()` function closes the supplied TCP connection, _conn_. - -If any operations are pending (such as <> -or <> they will be terminated with -an `NNG_ECLOSED` error condition. -Also, any new operations will fail with `NNG_ECLOSED` after the connection -is closed. - -NOTE: 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. - -NOTE: 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 <>. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_dialer.5.adoc b/docs/man/nng_tcp_dialer.5.adoc deleted file mode 100644 index 651afd02..00000000 --- a/docs/man/nng_tcp_dialer.5.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= nng_tcp_dialer(5) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_dialer - TCP dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_tcp_dialer_s nng_tcp_dialer; ----- - -== DESCRIPTION - -(((TCP, dialer))) -An `nng_tcp_dialer` is a handle to a TCP "`dialer`", which is responsible for -creating connections (<> objects) by connecting to -remote systems. - -NOTE: The `nng_tcp_dialer` object is used for raw TCP connections, and -should not be confused with a dialer object created using the -<> transport. - -TIP: Most NNG applications should not use this, but instead use the -<> transport instead. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_dialer_alloc.3tcp.adoc b/docs/man/nng_tcp_dialer_alloc.3tcp.adoc deleted file mode 100644 index 3e215695..00000000 --- a/docs/man/nng_tcp_dialer_alloc.3tcp.adoc +++ /dev/null @@ -1,50 +0,0 @@ -= nng_tcp_dialer_alloc(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_dialer_alloc - allocate TCP dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tcp_dialer_alloc(nng_tcp_dialer *dp); ----- - -== DESCRIPTION - -The `nng_tcp_dialer_alloc()` allocates a TCP dialer, which can be used -to create outgoing connections over TCP, and stores a pointer to it -it in the location referenced by _dp_. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_dialer_close.3tcp.adoc b/docs/man/nng_tcp_dialer_close.3tcp.adoc deleted file mode 100644 index b325a3a0..00000000 --- a/docs/man/nng_tcp_dialer_close.3tcp.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= nng_tcp_dialer_close(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_dialer_close - close TCP dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tcp_dialer_close(nng_tcp_dialer *d); ----- - -== DESCRIPTION - -The `nng_tcp_dialer_close()` function closes the supplied TCP dialer _d_, -but does not free the underlying resources associated with it. - -If any <> operations using _d_ are -in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -Furthermore any future accesses to the dialer _d_ will also result in -`NNG_ECLOSED`. - -NOTE: This function does not release the memory for the dialer, so the -application should still free the memory using -<> -once it is certain that nothing else is using it. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_dialer_dial.3tcp.adoc b/docs/man/nng_tcp_dialer_dial.3tcp.adoc deleted file mode 100644 index 3f0c8ba6..00000000 --- a/docs/man/nng_tcp_dialer_dial.3tcp.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= nng_tcp_dialer_dial(3tcp) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_dialer_dial - initiate outgoing TCP connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tcp_dialer_dial(nng_tcp_dialer *d, const nng_sockaddr *sa, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_tcp_dialer_dial()` attempts to establish a TCP connection to the -remote peer identified by _sa_, using the dialer _d_. -The operation is completed asynchronously, using _aio_. - -The address _sa_ must be in the `NNG_AF_INET` or `NNG_AF_INET6` families, -and have a valid IPv4 or IPv6 address and TCP port number. - -If a connection is successfully established, the _aio_ will have the -resulting <> stored as its first output. -(See <>.) - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_EADDRINVAL`:: The address specified is invalid. -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECLOSED`:: The dialer is closed. -`NNG_ECONNREFUSED`:: The connection was refused by the server. -`NNG_ECONNRESET`:: The connection was reset by the server. -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_dialer_free.3tcp.adoc b/docs/man/nng_tcp_dialer_free.3tcp.adoc deleted file mode 100644 index 7b15fc39..00000000 --- a/docs/man/nng_tcp_dialer_free.3tcp.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_tcp_dialer_free(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_dialer_free - free TCP dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tcp_dialer_free(nng_tcp_dialer *d); ----- - -== DESCRIPTION - -The `nng_tcp_dialer_free()` function closes the supplied TCP dialer _d_, -and frees the underlying resources associated with it. - -If any <> operations using _d_ are -in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -WARNING: It is important that the application ensure that no further accesses -are made to _d_, as the memory backing it will be reclaimed for other uses. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_dialer_getopt.3tcp.adoc b/docs/man/nng_tcp_dialer_getopt.3tcp.adoc deleted file mode 100644 index b99b17eb..00000000 --- a/docs/man/nng_tcp_dialer_getopt.3tcp.adoc +++ /dev/null @@ -1,69 +0,0 @@ -= nng_tcp_dialer_getopt(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_dialer_getopt - get option from TCP dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tcp_getopt(nng_tcp_dialer *d, const char *name, void *data, size_t *sizep); ----- - -== DESCRIPTION - -The `nng_tcp_dialer_getopt()` is used to retrieve the value of the option _name_ -for the <> _d_. -The size of the buffer located at _data_ to receive the copy is passed by the -caller at the location referenced by _sizep_. -If this size is sufficient to hold the entire object, the object is copied into -the buffer specified by _data_. -In either event, the size of the source object (the amount of data copied, -or that would have been copied if sufficient space were available) is stored -at the location of _sizep_. - -=== Options - -The options specifically suppported for retrieval from TCP dialers are: - -* <> -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The dialer is closed. -`NNG_EINVAL`:: There was insufficient space to receive the object. - The amount of data actually needed is returned in _sizep_. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EWRITEONLY`:: The option _name_ may not read. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_dialer_setopt.3tcp.adoc b/docs/man/nng_tcp_dialer_setopt.3tcp.adoc deleted file mode 100644 index ae06cc3c..00000000 --- a/docs/man/nng_tcp_dialer_setopt.3tcp.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= nng_tcp_dialer_setopt(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_dialer_setopt - set option on TCP dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tcp_dialer_setopt(nng_tcp_dialer *d, const char *name, const void *data, size_t size); ----- - -== DESCRIPTION - -The `nng_tcp_dialer_setopt()` is used to set the option _name_ for the -<> _d_. -The value to set is copied from _data_, which should be _size_ bytes -in length. - -=== Options - -The options specifically suppported for modification on TCP dialers are: - -* <> -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The dialer is closed. -`NNG_EINVAL`:: Either _data_ or _size_ are invalid. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EREADONLY`:: The option _name_ may not be modified. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_free.3tcp.adoc b/docs/man/nng_tcp_free.3tcp.adoc deleted file mode 100644 index c87380cd..00000000 --- a/docs/man/nng_tcp_free.3tcp.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_tcp_free(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_free - free TCP connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tcp_free(nng_tcp *conn); ----- - -== DESCRIPTION - -The `nng_tcp_free()` function closes the supplied TCP connection, _conn_, -and frees the underlying resources associated with it. - -If any operations are pending (such as <> -or <> they will be terminated with -an `NNG_ECLOSED` error condition. - -WARNING: It is important that the application ensure that no further accesses -are made to _conn_, as the memory backing it will be reclaimed for other uses. - -NOTE: 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. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_getopt.3tcp.adoc b/docs/man/nng_tcp_getopt.3tcp.adoc deleted file mode 100644 index f785791b..00000000 --- a/docs/man/nng_tcp_getopt.3tcp.adoc +++ /dev/null @@ -1,68 +0,0 @@ -= nng_tcp_getopt(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_getopt - get option from TCP connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tcp_getopt(nng_tcp *conn, const char *name, void *data, size_t *sizep); ----- - -== DESCRIPTION - -The `nng_tcp_getopt()` is used to retrieve the value of the option _name_ for -the <> _conn_. -The size of the buffer located at _data_ to receive the copy is passed by the -caller at the location referenced by _sizep_. -If this size is sufficient to hold the entire object, the object is copied into -the buffer specified by _data_. -In either event, the size of the source object (the amount of data copied, -or that would have been copied if sufficient space were available) is stored -at the location of _sizep_. - -=== Options - -The options specifically suppported for retrieval from TCP connections are: - -* <> -* <> -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The connection _conn_ is closed. -`NNG_EINVAL`:: There was insufficient space to receive the object. - The amount of data actually needed is returned in _sizep_. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EWRITEONLY`:: The option _name_ may not read. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_listener.5.adoc b/docs/man/nng_tcp_listener.5.adoc deleted file mode 100644 index ffa6fb53..00000000 --- a/docs/man/nng_tcp_listener.5.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_tcp_listener(5) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_listener - TCP listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_tcp_dialer_s nng_tcp_dialer; ----- - -== DESCRIPTION - -(((TCP, listener))) -An `nng_tcp_listener` is a handle to a TCP "`listener`", which is responsible -for accepting connections (<> objects) from remote -systems. - -NOTE: The `nng_tcp_listener` object is used for raw TCP connections, and -should not be confused with a listener object created using the -<> transport. - -TIP: Most NNG applications should not use this, but instead use the -<> transport instead. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_listener_accept.3tcp.adoc b/docs/man/nng_tcp_listener_accept.3tcp.adoc deleted file mode 100644 index a50d709e..00000000 --- a/docs/man/nng_tcp_listener_accept.3tcp.adoc +++ /dev/null @@ -1,67 +0,0 @@ -= nng_tcp_listener_accept(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_listener_accept - accept incoming TCP connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tcp_listener_accept(nng_tcp_listener *l, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_tcp_listener_accept()` attempts to accept an incoming TCP connection -from a remote peer, using the listener _l_. -The operation is completed asynchronously, using _aio_. - -This operation can only be done after the listener is already bound to -a TCP port and is <>. - -If a connection is successfully established, the _aio_ will have the -resulting <> stored as its first output. -(See <>.) - -The address of the remote peer can be determined using the -<> option with the -<> function on the -returned <>. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECLOSED`:: The listener is closed. -`NNG_ECONNRESET`:: The TCP connection was reset by the peer. -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ESTATE`:: The listener is not not listening. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_listener_alloc.3tcp.adoc b/docs/man/nng_tcp_listener_alloc.3tcp.adoc deleted file mode 100644 index 718ac7a5..00000000 --- a/docs/man/nng_tcp_listener_alloc.3tcp.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= nng_tcp_listener_alloc(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_listener_alloc - allocate TCP listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tcp_listener_alloc(nng_tcp_listener *lp); ----- - -== DESCRIPTION - -The `nng_tcp_listener_alloc()` allocates a TCP listener, which can be used -to accept incoming connections over TCP, and stores a pointer to it -it in the location referenced by _lp_. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_listener_close.3tcp.adoc b/docs/man/nng_tcp_listener_close.3tcp.adoc deleted file mode 100644 index a85d3675..00000000 --- a/docs/man/nng_tcp_listener_close.3tcp.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= nng_tcp_listener_close(3tcp) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_listener_close - close TCP listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tcp_listener_close(nng_tcp_listener *l); ----- - -== DESCRIPTION - -The `nng_tcp_listener_close()` function closes the supplied TCP listener _l_, -but does not free the underlying resources associated with it. - -If any <> operations using _l_ -are in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -Furthermore any future accesses to the listener _l_ will also result in -`NNG_ECLOSED`. - -NOTE: This function does not release the memory for the listener, so the -application should still free the memory using -<> -once it is certain that nothing else is using it. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_listener_free.3tcp.adoc b/docs/man/nng_tcp_listener_free.3tcp.adoc deleted file mode 100644 index a91a67b4..00000000 --- a/docs/man/nng_tcp_listener_free.3tcp.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= nng_tcp_listener_free(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_listener_free - free TCP listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tcp_listener_free(nng_tcp_listener *l); ----- - -== DESCRIPTION - -The `nng_tcp_listener_free()` function closes the supplied TCP listener _l_, -and frees the underlying resources associated with it. - -If any <> operations using _l_ -are in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -WARNING: It is important that the application ensure that no further accesses -are made to _l_, as the memory backing it will be reclaimed for other uses. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_listener_getopt.3tcp.adoc b/docs/man/nng_tcp_listener_getopt.3tcp.adoc deleted file mode 100644 index 29a34192..00000000 --- a/docs/man/nng_tcp_listener_getopt.3tcp.adoc +++ /dev/null @@ -1,69 +0,0 @@ -= nng_tcp_listener_getopt(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_listener_getopt - get option from TCP listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tcp_listener_getopt(nng_tcp_listener *l, const char *name, void *data, size_t *sizep); ----- - -== DESCRIPTION - -The `nng_tcp_listener_getopt()` is used to retrieve the value of the option _name_ for the <> _l_. -The size of the buffer located at _data_ to receive the copy is passed by the -caller at the location referenced by _sizep_. -If this size is sufficient to hold the entire object, the object is copied into -the buffer specified by _data_. -In either event, the size of the source object (the amount of data copied, -or that would have been copied if sufficient space were available) is stored -at the location of _sizep_. - -=== Options - -The options specifically suppported for retrieval from TCP listeners are: - -* <> -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The dialer is closed. -`NNG_EINVAL`:: There was insufficient space to receive the object. - The amount of data actually needed is returned in _sizep_. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EWRITEONLY`:: The option _name_ may not read. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<> - diff --git a/docs/man/nng_tcp_listener_listen.3tcp.adoc b/docs/man/nng_tcp_listener_listen.3tcp.adoc deleted file mode 100644 index a50caf38..00000000 --- a/docs/man/nng_tcp_listener_listen.3tcp.adoc +++ /dev/null @@ -1,71 +0,0 @@ -= nng_tcp_listener_listen(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_listener_listen - bind listener to TCP port - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tcp_listener_listen(nng_tcp_listener l, const nng_sockaddr *sa); ----- - -== DESCRIPTION - -The `nng_tcp_listener_listen()` attempts to bind the listener _l_ -to the local address specified by _sa_, which must be in the -`NNG_AF_INET` or `NNG_AF_INET6` address family. - -This also sets the underlying port into passive mode, ready to -accept an incoming connection, and established a listen queue -for receiving incoming connections. (The queue depth is system -specific, but typically 128.) - -The actual IPv4 or IPv6 address in _sa_ may refer either to a locally -configured interface address, or to a zero-valued adddress to indicate -that all interfaces on the system should be bound. - -The TCP port number may also be zero. In this case the system will -choose a free TCP port at random, and use it. - -The chosen port number may be retrieved using the -<> option with the -<> function. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EADDRINUSE`:: The address specified by _sa_ is already in use. -`NNG_EADDRINVAL`:: The address specified by _sa_ is invalid or unavailable. -`NNG_ECLOSED`:: The listener _l_ has been closed. -`NNG_ESTATE`:: The listener _l_ is already bound. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_listener_setopt.3tcp.adoc b/docs/man/nng_tcp_listener_setopt.3tcp.adoc deleted file mode 100644 index 7e69c472..00000000 --- a/docs/man/nng_tcp_listener_setopt.3tcp.adoc +++ /dev/null @@ -1,62 +0,0 @@ -= nng_tcp_listener_setopt(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_listener_setopt - set option on TCP listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tcp_listener_setopt(nng_tcp_listener *l, const char *name, const void *data, size_t size); ----- - -== DESCRIPTION - -The `nng_tcp_listener_setopt()` is used to set the option _name_ for the -<> _l_. -The value to set is copied from _data_, which should be _size_ bytes -in length. - -=== Options - -The options specifically suppported for modification on TCP listeners are: - -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The listener is closed. -`NNG_EINVAL`:: Either _data_ or _size_ are invalid. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EREADONLY`:: The option _name_ may not be modified. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_recv.3tcp.adoc b/docs/man/nng_tcp_recv.3tcp.adoc deleted file mode 100644 index 787ebfd3..00000000 --- a/docs/man/nng_tcp_recv.3tcp.adoc +++ /dev/null @@ -1,74 +0,0 @@ -= nng_tcp_recv(3tcp) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_recv - receive from TCP connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tcp_recv(nng_tcp *conn, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_tcp_recv()` function starts an asynchronous receive from the -TCP connection _conn_, into the scatter/gather vector located in the -asynchronous I/O structure _aio_. - -NOTE: The <> function must have been -called first, to set the scatter/gather vector for _aio_. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, -and the final result may be obtained via -<>. -That result will either be zero or an error code. - -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 -<>. - -NOTE: While TCP has the notion of urgent (out-of-band) delivery, that is -used by very few protocols and this API does not support it. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_send.3tcp.adoc b/docs/man/nng_tcp_send.3tcp.adoc deleted file mode 100644 index 806dd9c0..00000000 --- a/docs/man/nng_tcp_send.3tcp.adoc +++ /dev/null @@ -1,73 +0,0 @@ -= nng_tcp_send(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_send - send to TCP connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tcp_send(nng_tcp *conn, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_tcp_send()` function starts an asynchronous send over the -TCP connection _conn_ from the scatter/gather vector located in the -asynchronous I/O structure _aio_. - -NOTE: The <> function must have been -called first, to set the scatter/gather vector for _aio_. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, and the final -result may be obtained via <>. -That result will either be zero or an error code. - -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 -<>. - -NOTE: While TCP has the notion of urgent (out-of-band) delivery, that is -used by very few protocols and this API does not support it. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tcp_setopt.3tcp.adoc b/docs/man/nng_tcp_setopt.3tcp.adoc deleted file mode 100644 index b47bf62e..00000000 --- a/docs/man/nng_tcp_setopt.3tcp.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= nng_tcp_setopt(3tcp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_setopt - set option on TCP connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tcp_setopt(nng_tcp *conn, const char *name, const void *data, size_t size); ----- - -== DESCRIPTION - -The `nng_tcp_setopt()` is used to set the option _name_ for the -<> _conn_. -The value to set is copied from _data_, which should be _size_ bytes -in length. - -=== Options - -The options specifically suppported for modification on TCP -connections are: - -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The connection _conn_ is closed. -`NNG_EINVAL`:: Either _data_ or _size_ are invalid. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EREADONLY`:: The option _name_ may not be modified. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_close.3tls.adoc b/docs/man/nng_tls_close.3tls.adoc deleted file mode 100644 index 49836965..00000000 --- a/docs/man/nng_tls_close.3tls.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= nng_tls_close(3tls) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_close - close TLS connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tls_close(nng_tls *conn); ----- - -== DESCRIPTION - -The `nng_tls_close()` function closes the supplied TLS connection, _conn_. - -If any operations are pending (such as <> -or <> they will be terminated with -an `NNG_ECLOSED` error condition. -Also, any new operations will fail with `NNG_ECLOSED` after the connection -is closed. - -NOTE: 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. - -NOTE: 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 <>. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_dialer.5.adoc b/docs/man/nng_tls_dialer.5.adoc deleted file mode 100644 index 86c44cea..00000000 --- a/docs/man/nng_tls_dialer.5.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= nng_tls_dialer(5) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_dialer - TLS dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_tls_dialer_s nng_tls_dialer; ----- - -== DESCRIPTION - -(((TLS, dialer))) -An `nng_tls_dialer` is a handle to a TLS "`dialer`", which is responsible for -creating connections (<> objects) by connecting to -remote systems. - -NOTE: The `nng_tls_dialer` object is used for raw IPC connections, and -should not be confused with a dialer object created using the -<> transport. - -TIP: Most NNG applications should not use this, but instead use the -<> transport instead. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_dialer_alloc.3tls.adoc b/docs/man/nng_tls_dialer_alloc.3tls.adoc deleted file mode 100644 index 6a59eaee..00000000 --- a/docs/man/nng_tls_dialer_alloc.3tls.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_tls_dialer_alloc(3tls) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_dialer_alloc - allocate TLS dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tls_dialer_alloc(nng_tls_dialer *dp); ----- - -== DESCRIPTION - -The `nng_tls_dialer_alloc()` allocates a TLS dialer, which can be used -to create outgoing connections over TLS, and stores a pointer to it -it in the location referenced by _dp_. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ENOTSUP`:: TLS support not configured in library. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_dialer_close.3tls.adoc b/docs/man/nng_tls_dialer_close.3tls.adoc deleted file mode 100644 index 19ca0bd1..00000000 --- a/docs/man/nng_tls_dialer_close.3tls.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_tls_dialer_close(3tls) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_dialer_close - close TLS dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tls_dialer_close(nng_tls_dialer *d); ----- - -== DESCRIPTION - -The `nng_tls_dialer_close()` function closes the supplied TCP dialer _d_, -but does not free the underlying resources associated with it. - -If any <> operations using _d_ are -in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -Furthermore any future accesses to the dialer _d_ will also result in -`NNG_ECLOSED`. - -NOTE: This function does not release the memory for the dialer, so the -application should still free the memory using -<> -once it is certain that nothing else is using it. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_dialer_dial.3tls.adoc b/docs/man/nng_tls_dialer_dial.3tls.adoc deleted file mode 100644 index 31d9036d..00000000 --- a/docs/man/nng_tls_dialer_dial.3tls.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= nng_tls_dialer_dial(3tls) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_dialer_dial - initiate outgoing TLS connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tls_dialer_dial(nng_tls_dialer *d, const nng_sockaddr *sa, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_tls_dialer_dial()` attempts to establish a TLS connection to the -remote peer identified by _sa_, using the dialer _d_. -The operation is completed asynchronously, using _aio_. - -The address _sa_ must be in the `NNG_AF_INET` or `NNG_AF_INET6` families, -and have a valid IPv4 or IPv6 address and TCP port number. - -If a connection is successfully established, the _aio_ will have the -resulting <> stored as its first output. -(See <>.) - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_EADDRINVAL`:: The address specified is invalid. -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECLOSED`:: The dialer is closed. -`NNG_ECONNREFUSED`:: The connection was refused by the server. -`NNG_ECONNRESET`:: The connection was reset by the server. -`NNG_ECRYPTO`:: Cryptographic or certificate validation error. -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_dialer_free.3tls.adoc b/docs/man/nng_tls_dialer_free.3tls.adoc deleted file mode 100644 index b5e7b2bf..00000000 --- a/docs/man/nng_tls_dialer_free.3tls.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_tls_dialer_free(3tls) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_dialer_free - free TLS dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tls_dialer_free(nng_tls_dialer *d); ----- - -== DESCRIPTION - -The `nng_tls_dialer_free()` function closes the supplied TLS dialer _d_, -and frees the underlying resources associated with it. - -If any <> operations using _d_ are -in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -WARNING: It is important that the application ensure that no further accesses -are made to _d_, as the memory backing it will be reclaimed for other uses. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_dialer_getopt.3tls.adoc b/docs/man/nng_tls_dialer_getopt.3tls.adoc deleted file mode 100644 index 6790092f..00000000 --- a/docs/man/nng_tls_dialer_getopt.3tls.adoc +++ /dev/null @@ -1,73 +0,0 @@ -= nng_tls_dialer_getopt(3tls) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_dialer_getopt - get option from TLS dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tls_getopt(nng_tls_dialer *d, const char *name, void *data, size_t *sizep); ----- - -== DESCRIPTION - -The `nng_tls_dialer_getopt()` is used to retrieve the value of the option _name_ -for the <> _d_. -The size of the buffer located at _data_ to receive the copy is passed by the -caller at the location referenced by _sizep_. -If this size is sufficient to hold the entire object, the object is copied into -the buffer specified by _data_. -In either event, the size of the source object (the amount of data copied, -or that would have been copied if sufficient space were available) is stored -at the location of _sizep_. - -=== Options - -The options specifically suppported for retrieval from TLS dialers are: - -* <> -* <> -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The dialer is closed. -`NNG_EINVAL`:: There was insufficient space to receive the object. - The amount of data actually needed is returned in _sizep_. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EWRITEONLY`:: The option _name_ may not read. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> - diff --git a/docs/man/nng_tls_dialer_setopt.3tls.adoc b/docs/man/nng_tls_dialer_setopt.3tls.adoc deleted file mode 100644 index e7999c5b..00000000 --- a/docs/man/nng_tls_dialer_setopt.3tls.adoc +++ /dev/null @@ -1,69 +0,0 @@ -= nng_tls_dialer_setopt(3tls) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_dialer_setopt - set option on TLS dialer - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tls_dialer_setopt(nng_tls_dialer *d, const char *name, const void *data, size_t size); ----- - -== DESCRIPTION - -The `nng_tls_dialer_setopt()` is used to set the option _name_ for the -<> _d_. -The value to set is copied from _data_, which should be _size_ bytes -in length. - -=== Options - -The options specifically suppported for modification on TLS dialers are: - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The dialer is closed. -`NNG_EINVAL`:: Either _data_ or _size_ are invalid. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EREADONLY`:: The option _name_ may not be modified. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_free.3tls.adoc b/docs/man/nng_tls_free.3tls.adoc deleted file mode 100644 index 62c2a81d..00000000 --- a/docs/man/nng_tls_free.3tls.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nng_tls_free(3tls) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_free - free TLS connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tls_free(nng_tls *conn); ----- - -== DESCRIPTION - -The `nng_tls_free()` function closes the supplied TLS connection, _conn_, -and frees the underlying resources associated with it. - -If any operations are pending (such as <> -or <> they will be terminated with -an `NNG_ECLOSED` error condition. - -WARNING: It is important that the application ensure that no further accesses -are made to _conn_, as the memory backing it will be reclaimed for other uses. - -NOTE: 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. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_getopt.3tls.adoc b/docs/man/nng_tls_getopt.3tls.adoc deleted file mode 100644 index 87c8287c..00000000 --- a/docs/man/nng_tls_getopt.3tls.adoc +++ /dev/null @@ -1,70 +0,0 @@ -= nng_tls_getopt(3tls) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_getopt - get option from TLS connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tls_getopt(nng_tls *conn, const char *name, void *data, size_t *sizep); ----- - -== DESCRIPTION - -The `nng_tls_getopt()` is used to retrieve the value of the option _name_ for -the <> _conn_. -The size of the buffer located at _data_ to receive the copy is passed by the -caller at the location referenced by _sizep_. -If this size is sufficient to hold the entire object, the object is copied into -the buffer specified by _data_. -In either event, the size of the source object (the amount of data copied, -or that would have been copied if sufficient space were available) is stored -at the location of _sizep_. - -=== Options - -The options specifically suppported for retrieval from TLS connections are: - -* <> -* <> -* <> -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The connection _conn_ is closed. -`NNG_EINVAL`:: There was insufficient space to receive the object. - The amount of data actually needed is returned in _sizep_. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EWRITEONLY`:: The option _name_ may not read. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_listener.5.adoc b/docs/man/nng_tls_listener.5.adoc deleted file mode 100644 index 6854aa57..00000000 --- a/docs/man/nng_tls_listener.5.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_tls_listener(5) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_listener - TLS listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_tls_dialer_s nng_tls_dialer; ----- - -== DESCRIPTION - -(((TLS, listener))) -An `nng_tls_listener` is a handle to a TLS "`listener`", which is responsible -for accepting connections (<> objects) from remote -systems. - -NOTE: The `nng_tls_listener` object is used for raw TLS over TCP connections, and -should not be confused with a listener object created using the -<> transport. - -TIP: Most NNG applications should not use this, but instead use the -<> transport instead. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_listener_accept.3tls.adoc b/docs/man/nng_tls_listener_accept.3tls.adoc deleted file mode 100644 index 5d9b3952..00000000 --- a/docs/man/nng_tls_listener_accept.3tls.adoc +++ /dev/null @@ -1,70 +0,0 @@ -= nng_tls_listener_accept(3tls) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_listener_accept - accept incoming TLS connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tls_listener_accept(nng_tls_listener *l, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_tls_listener_accept()` attempts to accept an incoming TLS connection -from a remote peer, using the listener _l_. -The operation is completed asynchronously, using _aio_. - -This operation can only be done after the listener is already bound to -a TCP port and is <>. - -If a connection is successfully established, the _aio_ will have the -resulting <> stored as its first output. -(See <>.) - -The address of the remote peer can be determined using the -<> option with the -<> function on the -returned <>. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECLOSED`:: The listener is closed. -`NNG_ECONNRESET`:: The connection was reset by the peer. -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ESTATE`:: The listener is not not listening. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_listener_alloc.3tls.adoc b/docs/man/nng_tls_listener_alloc.3tls.adoc deleted file mode 100644 index 88c4981a..00000000 --- a/docs/man/nng_tls_listener_alloc.3tls.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_tls_listener_alloc(3tls) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_listener_alloc - allocate TLS listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tls_listener_alloc(nng_tls_listener *lp); ----- - -== DESCRIPTION - -The `nng_tls_listener_alloc()` allocates a TLS listener, which can be used -to accept incoming connections over TLS, and stores a pointer to it -it in the location referenced by _lp_. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ENOTSUP`:: TLS support not configured in library. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_listener_close.3tls.adoc b/docs/man/nng_tls_listener_close.3tls.adoc deleted file mode 100644 index 26120cee..00000000 --- a/docs/man/nng_tls_listener_close.3tls.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_tls_listener_close(3tls) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_listener_close - close TLS listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tls_listener_close(nng_tls_listener *l); ----- - -== DESCRIPTION - -The `nng_tls_listener_close()` function closes the supplied TLS listener _l_, -but does not free the underlying resources associated with it. - -If any <> operations using _l_ -are in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -Furthermore any future accesses to the listener _l_ will also result in -`NNG_ECLOSED`. - -NOTE: This function does not release the memory for the listener, so the -application should still free the memory using -<> -once it is certain that nothing else is using it. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_listener_free.3tls.adoc b/docs/man/nng_tls_listener_free.3tls.adoc deleted file mode 100644 index 067a803a..00000000 --- a/docs/man/nng_tls_listener_free.3tls.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_tls_listener_free(3tls) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_listener_free - free TLS listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tls_listener_free(nng_tls_listener *l); ----- - -== DESCRIPTION - -The `nng_tls_listener_free()` function closes the supplied TLS listener _l_, -and frees the underlying resources associated with it. - -If any <> operations using _l_ -are in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -WARNING: It is important that the application ensure that no further accesses -are made to _l_, as the memory backing it will be reclaimed for other uses. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_listener_getopt.3tls.adoc b/docs/man/nng_tls_listener_getopt.3tls.adoc deleted file mode 100644 index 45abda1b..00000000 --- a/docs/man/nng_tls_listener_getopt.3tls.adoc +++ /dev/null @@ -1,72 +0,0 @@ -= nng_tls_listener_getopt(3tls) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_listener_getopt - get option from TLS listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tls_listener_getopt(nng_tls_listener *l, const char *name, void *data, size_t *sizep); ----- - -== DESCRIPTION - -The `nng_tls_listener_getopt()` is used to retrieve the value of the option -_name_ for the <> _l_. -The size of the buffer located at _data_ to receive the copy is passed by the -caller at the location referenced by _sizep_. -If this size is sufficient to hold the entire object, the object is copied into -the buffer specified by _data_. -In either event, the size of the source object (the amount of data copied, -or that would have been copied if sufficient space were available) is stored -at the location of _sizep_. - -=== Options - -The options specifically suppported for retrieval from TLS listeners are: - -* <> -* <> -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The dialer is closed. -`NNG_EINVAL`:: There was insufficient space to receive the object. - The amount of data actually needed is returned in _sizep_. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EWRITEONLY`:: The option _name_ may not read. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> - diff --git a/docs/man/nng_tls_listener_listen.3tls.adoc b/docs/man/nng_tls_listener_listen.3tls.adoc deleted file mode 100644 index 4fd6bf18..00000000 --- a/docs/man/nng_tls_listener_listen.3tls.adoc +++ /dev/null @@ -1,73 +0,0 @@ -= nng_tls_listener_listen(3tls) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_listener_listen - bind listener to TLS port - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tls_listener_listen(nng_tls_listener l, const nng_sockaddr *sa); ----- - -== DESCRIPTION - -The `nng_tls_listener_listen()` attempts to bind the listener _l_ -to the local address specified by _sa_, which must be in the -`NNG_AF_INET` or `NNG_AF_INET6` address family. - -This also sets the underlying port into passive mode, ready to -accept an incoming connection, and established a listen queue -for receiving incoming connections. (The queue depth is system -specific, but typically 128.) - -The actual IPv4 or IPv6 address in _sa_ may refer either to a locally -configured interface address, or to a zero-valued adddress to indicate -that all interfaces on the system should be bound. - -The TCP port number may also be zero. In this case the system will -choose a free TCP port at random, and use it. - -The chosen port number may be retrieved using the -<> option with the -<> function. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EADDRINUSE`:: The address specified by _sa_ is already in use. -`NNG_EADDRINVAL`:: The address specified by _sa_ is invalid or unavailable. -`NNG_ECLOSED`:: The listener _l_ has been closed. -`NNG_ECRYPTO`:: Cryptographic or certificate error. -`NNG_ESTATE`:: The listener _l_ is already bound. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_listener_setopt.3tls.adoc b/docs/man/nng_tls_listener_setopt.3tls.adoc deleted file mode 100644 index 7254fddb..00000000 --- a/docs/man/nng_tls_listener_setopt.3tls.adoc +++ /dev/null @@ -1,67 +0,0 @@ -= nng_tls_listener_setopt(3tls) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_listener_setopt - set option on TLS listener - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tls_listener_setopt(nng_tls_listener *l, const char *name, const void *data, size_t size); ----- - -== DESCRIPTION - -The `nng_tls_listener_setopt()` is used to set the option _name_ for the -<> _l_. -The value to set is copied from _data_, which should be _size_ bytes -in length. - -=== Options - -The options specifically suppported for modification on TLS listeners are: - -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The listener is closed. -`NNG_EINVAL`:: Either _data_ or _size_ are invalid. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EREADONLY`:: The option _name_ may not be modified. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_recv.3tls.adoc b/docs/man/nng_tls_recv.3tls.adoc deleted file mode 100644 index 39362a13..00000000 --- a/docs/man/nng_tls_recv.3tls.adoc +++ /dev/null @@ -1,73 +0,0 @@ -= nng_tls_recv(3tls) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_recv - receive from TLS connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tls_recv(nng_tls *conn, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_tls_recv()` function starts an asynchronous receive from the -TLS connection _conn_, into the scatter/gather vector located in the -asynchronous I/O structure _aio_. - -NOTE: The <> function must have been -called first, to set the scatter/gather vector for _aio_. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, -and the final result may be obtained via -<>. -That result will either be zero or an error code. - -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 -<>. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECRYPTO`:: Cryptographic or certificate error. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_send.3tls.adoc b/docs/man/nng_tls_send.3tls.adoc deleted file mode 100644 index a82c6557..00000000 --- a/docs/man/nng_tls_send.3tls.adoc +++ /dev/null @@ -1,72 +0,0 @@ -= nng_tls_send(3tls) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_send - send to TLS connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_tls_send(nng_tls *conn, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_tls_send()` function starts an asynchronous send over the -TLS connection _conn_ from the scatter/gather vector located in the -asynchronous I/O structure _aio_. - -NOTE: The <> function must have been -called first, to set the scatter/gather vector for _aio_. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, and the final -result may be obtained via <>. -That result will either be zero or an error code. - -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 -<>. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_ECRYPTO`:: Cryptographic or certificate error. -`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<>, -<>, -<> diff --git a/docs/man/nng_tls_setopt.3tls.adoc b/docs/man/nng_tls_setopt.3tls.adoc deleted file mode 100644 index 3ba4a979..00000000 --- a/docs/man/nng_tls_setopt.3tls.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= nng_tls_setopt(3tls) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_setopt - set option on TLS connection - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_tls_setopt(nng_tls *conn, const char *name, const void *data, size_t size); ----- - -== DESCRIPTION - -The `nng_tls_setopt()` is used to set the option _name_ for the -<> _conn_. -The value to set is copied from _data_, which should be _size_ bytes -in length. - -=== Options - -The options specifically suppported for modification on TLS connections are: - -* <> -* <> - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The connection _conn_ is closed. -`NNG_EINVAL`:: Either _data_ or _size_ are invalid. -`NNG_ENOTSUP`:: The option _name_ is not supported. -`NNG_EREADONLY`:: The option _name_ may not be modified. - -== SEE ALSO - -[.text-left] -<>, -<>, -<>, -<>, -<>, -<> -- cgit v1.2.3-70-g09d2