diff options
| author | Garrett D'Amore <garrett@damore.org> | 2019-01-21 22:40:10 -0800 |
|---|---|---|
| committer | Garrett D'Amore <garrett@damore.org> | 2019-02-16 19:22:27 -0800 |
| commit | 5cf750697624d4fd63cfe26921209d7c30e1a2d2 (patch) | |
| tree | bf11695e5f1ec5e400c87da0cc6ff23935a2eeff /docs/man | |
| parent | ca655b9db689ee0e655248b1a9f166b8db6cc984 (diff) | |
| download | nng-5cf750697624d4fd63cfe26921209d7c30e1a2d2.tar.gz nng-5cf750697624d4fd63cfe26921209d7c30e1a2d2.tar.bz2 nng-5cf750697624d4fd63cfe26921209d7c30e1a2d2.zip | |
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.
Diffstat (limited to 'docs/man')
83 files changed, 1732 insertions, 3892 deletions
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. <info@staysail.tech> # Copyright 2018 Capitar IT Group BV <info@capitar.com> -# Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> # Copyright 2019 Devolutions <info@devolutions.net> # # 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 <<nng.7#,_nng_>> 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_. |=== -|<<nng_alloc.3#,nng_alloc()>>|allocate memory -|<<nng_free.3#,nng_free()>>|free memory -|<<nng_strdup.3#,nng_strdup()>>|duplicate string -|<<nng_strerror.3#,nng_strerror()>>|return an error description -|<<nng_strfree.3#,nng_strfree()>>|free string -|<<nng_version.3#,nng_version()>>|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. |=== -|<<nng_close.3#,nng_close()>>|close socket -|<<nng_dial.3#,nng_dial()>>|create and start dialer -|<<nng_getopt.3#,nng_getopt()>>|get socket option -|<<nng_listen.3#,nng_listen()>>|create and start listener -|<<nng_recv.3#,nng_recv()>>|receive data -|<<nng_send.3#,nng_send()>>|send data -|<<nng_setopt.3#,nng_setopt()>>|set socket option -|<<nng_socket_id.3#,nng_socket_id()>>|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. |=== -|<<nng_dial.3#,nng_dial()>>|create and start dialer -|<<nng_dialer_close.3#,nng_dialer_close()>>|close dialer -|<<nng_dialer_create.3#,nng_dialer_create()>>|create dialer -|<<nng_dialer_getopt.3#,nng_dialer_getopt()>>|get dialer option -|<<nng_dialer_id.3#,nng_dialer_id()>>|get numeric dialer identifier -|<<nng_dialer_setopt.3#,nng_dialer_setopt()>>|set dialer option -|<<nng_dialer_start.3#,nng_dialer_start()>>|start dialer -|<<nng_listen.3#,nng_listen()>>|create and start listener -|<<nng_listener_close.3#,nng_listener_close()>>|close listener -|<<nng_listener_create.3#,nng_listener_create()>>|create listener -|<<nng_listener_getopt.3#,nng_listener_getopt()>>|get listener option -|<<nng_listener_id.3#,nng_listener_id()>>|get numeric listener identifier -|<<nng_listener_setopt.3#,nng_listener_setopt()>>|set listener option -|<<nng_listener_start.3#,nng_listener_start()>>|start listener -|<<nng_pipe_close.3#,nng_pipe_close()>>|close pipe -|<<nng_pipe_dialer.3#,nng_pipe_dialer()>>|return dialer that created pipe -|<<nng_pipe_getopt.3#,nng_pipe_getopt()>>|get pipe option -|<<nng_pipe_id.3#,nng_pipe_id()>>|get numeric pipe identifier -|<<nng_pipe_listener.3#,nng_pipe_listener()>>|return listener that created pipe -|<<nng_pipe_notify.3#,nng_pipe_notify()>>|register pipe notification callback -|<<nng_pipe_socket.3#,nng_pipe_socket()>>|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. |=== -|<<nng_msg_alloc.3#,nng_msg_alloc()>>|allocate a message -|<<nng_msg_append.3#,nng_msg_append()>>|append to message body -|<<nng_msg_body.3#,nng_msg_body()>>|return message body -|<<nng_msg_chop.3#,nng_msg_chop()>>|remove data from end of message body -|<<nng_msg_clear.3#,nng_msg_clear()>>|clear message body -|<<nng_msg_dup.3#,nng_msg_dup()>>|duplicate a message -|<<nng_msg_free.3#,nng_msg_free()>>|free a message -|<<nng_msg_get_pipe.3#,nng_msg_get_pipe()>>|get pipe for message -|<<nng_msg_insert.3#,nng_msg_insert()>>|prepend to message body -|<<nng_msg_len.3#,nng_msg_len()>>|return the message body length -|<<nng_msg_realloc.3#,nng_msg_realloc()>>|reallocate a message -|<<nng_msg_set_pipe.3#,nng_msg_set_pipe()>>|set pipe for message -|<<nng_msg_trim.3#,nng_msg_trim()>>|remove data from start of message body -|<<nng_recvmsg.3#,nng_recvmsg()>>|receive a message -|<<nng_sendmsg.3#,nng_sendmsg()>>|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. |=== -|<<nng_msg_header.3#,nng_msg_header()>>|return message header -|<<nng_msg_header_append.3#,nng_msg_header_append()>>|append to message header -|<<nng_msg_header_chop.3#,nng_msg_header_chop()>>|remove data from end of message header -|<<nng_msg_header_clear.3#,nng_msg_header_clear()>>|clear message header -|<<nng_msg_header_insert.3#,nng_msg_header_insert()>>|prepend to message header -|<<nng_msg_header_len.3#,nng_msg_header_len()>>|return the message header length -|<<nng_msg_header_trim.3#,nng_msg_header_trim()>>|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 <<nng_send.3#,`nng_send()`>> 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 <<nng_aio.5#,`nng_aio`>>, 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: |=== -|<<nng_aio_abort.3#,nng_aio_abort()>>|abort asynchronous I/O operation -|<<nng_aio_alloc.3#,nng_aio_alloc()>>|allocate asynchronous I/O handle -|<<nng_aio_begin.3#,nng_aio_begin()>>|begin asynchronous I/O operation -|<<nng_aio_cancel.3#,nng_aio_cancel()>>|cancel asynchronous I/O operation -|<<nng_aio_count.3#,nng_aio_count()>>|return number of bytes transferred -|<<nng_aio_defer.3#,nng_aio_defer()>>|defer asynchronous I/O operation -|<<nng_aio_finish.3#,nng_aio_finish()>>|finish asynchronous I/O operation -|<<nng_aio_free.3#,nng_aio_free()>>|free asynchronous I/O handle -|<<nng_aio_get_input.3#,nng_aio_get_input()>>|return input parameter -|<<nng_aio_get_msg.3#,nng_aio_get_msg()>>|get message from an asynchronous receive -|<<nng_aio_get_output.3#,nng_aio_get_output()>>|return output result -|<<nng_aio_result.3#,nng_aio_result()>>|return result of asynchronous operation -|<<nng_aio_set_input.3#,nng_aio_set_input()>>|set input parameter -|<<nng_aio_set_iov.3#,nng_aio_set_iov()>>|set scatter/gather vector -|<<nng_aio_set_msg.3#,nng_aio_set_msg()>>|set message for an asynchronous send -|<<nng_aio_set_output.3#,nng_aio_set_output()>>|set output result -|<<nng_aio_set_timeout.3#,nng_aio_set_timeout()>>|set asynchronous I/O timeout -|<<nng_aio_stop.3#,nng_aio_stop()>>|stop asynchronous I/O operation -|<<nng_aio_wait.3#,nng_aio_wait()>>|wait for asynchronous I/O operation -|<<nng_recv_aio.3#,nng_recv_aio()>>|receive message asynchronously -|<<nng_send_aio.3#,nng_send_aio()>>|send message asynchronously -|<<nng_sleep_aio.3#,nng_sleep_aio()>>|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: |=== -|<<nng_bus_open.3#,nng_bus_open()>>|open a bus socket -|<<nng_pair_open.3#,nng_pair_open()>>|open a pair socket -|<<nng_pub_open.3#,nng_pub_open()>>|open a pub socket -|<<nng_pull_open.3#,nng_pull_open()>>|open a pull socket -|<<nng_push_open.3#,nng_push_open()>>|open a push socket -|<<nng_rep_open.3#,nng_rep_open()>>|open a rep socket -|<<nng_req_open.3#,nng_req_open()>>|open a req socket -|<<nng_respondent_open.3#,nng_respondent_open()>>|open a respondent socket -|<<nng_sub_open.3#,nng_sub_open()>>|open a sub socket -|<<nng_surveyor_open.3#,nng_surveyor_open()>>|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. |=== -| <<nng_inproc_register.3#,nng_inproc_register()>>|register inproc transport -| <<nng_ipc_register.3#,nng_ipc_register()>>|register IPC transport -| <<nng_tcp_register.3#,nng_tcp_register()>>|register TCP transport -| <<nng_tls_register.3#,nng_tls_register()>>|register TLS transport -| <<nng_ws_register.3#,nng_ws_register()>>|register WebSocket transport -| <<nng_wss_register.3#,nng_wss_register()>>|register WebSocket Secure transport -| <<nng_zt_register.3#,nng_zt_register()>>|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. |=== -|<<nng_ctx_close.3#,nng_ctx_close()>>|close context -|<<nng_ctx_getopt.3#,nng_ctx_getopt()>>|get context option -|<<nng_ctx_id.3#,nng_ctx_id()>>|get numeric context identifier -|<<nng_ctx_open.3#,nng_ctx_open()>>|create context -|<<nng_ctx_recv.3#,nng_ctx_recv()>>|receive message using context asynchronously -|<<nng_ctx_send.3#,nng_ctx_send()>>|send message using context asynchronously -|<<nng_ctx_setopt.3#,nng_ctx_setopt()>>|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. |=== -|<<nng_stat_child.3#,nng_stat_child()>>|get child statistic -|<<nng_stat_desc.3#,nng_stat_name()>>|get statistic description -|<<nng_stat_name.3#,nng_stat_name()>>|get statistic name -|<<nng_stat_next.3#,nng_stat_next()>>|get next statistic -|<<nng_stat_string.3#,nng_stat_string()>>|get statistic string value -|<<nng_stat_timestamp.3#,nng_stat_timestamp()>>|get statistic timestamp -|<<nng_stat_type.3#,nng_stat_type()>>|get statistic type -|<<nng_stat_unit.3#,nng_stat_unit()>>|get statistic unit -|<<nng_stat_value.3#,nng_stat_valueg()>>|get statistic value -|<<nng_stats_free.3#,nng_stats_free()>>|free statistics -|<<nng_stats_get.3#,nng_stats_get()>>|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). |=== -|<<nng_url_clone.3#,nng_url_clone()>>|clone URL structure -|<<nng_url_free.3#,nng_url_free()>>|free URL structure -|<<nng_url_parse.3#,nng_url_parse()>>|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. |=== -|<<nng_clock.3supp#,nng_clock()>>|get time -|<<nng_cv_alloc.3supp#,nng_cv_alloc()>>|allocate condition variable -|<<nng_cv_free.3supp#,nng_cv_free()>>|free condition variable -|<<nng_cv_until.3supp#,nng_cv_until()>>|wait for condition or timeout -|<<nng_cv_wait.3supp#,nng_cv_wait()>>|wait for condition -|<<nng_cv_wake.3supp#,nng_cv_wake()>>|wake all waiters -|<<nng_cv_wake1.3supp#,nng_cv_wake1()>>|wake one waiter -|<<nng_msleep.3supp#,nng_msleep()>>|sleep for milliseconds -|<<nng_mtx_alloc.3supp#,nng_mtx_alloc()>>|allocate mutex -|<<nng_mtx_free.3supp#,nng_mtx_free()>>|free mutex -|<<nng_mtx_lock.3supp#,nng_mtx_lock()>>|lock mutex -|<<nng_mtx_unlock.3supp#,nng_mtx_unlock()>>|unlock mutex -|<<nng_opts_parse.3supp#,nng_opts_parse()>>|parse command line options -|<<nng_random.3supp#,nng_random()>>|get random number -|<<nng_thread_create.3supp#,nng_thread_create()>>|create thread -|<<nng_thread_destroy.3supp#,nng_thread_destroy()>>|reap thread -|=== - - -=== Supplemental TCP - -These TCP functions are available for use with direct TCP access. -Most applications won't need to use these. - -|=== -|<<nng_tcp_close.3tcp#,nng_tcp_close()>>|close TCP connection -|<<nng_tcp_dialer_alloc.3tcp#,nng_tcp_dialer_alloc()>>|allocate TCP dialer -|<<nng_tcp_dialer_close.3tcp#,nng_tcp_dialer_close()>>|close TCP dialer -|<<nng_tcp_dialer_dial.3tcp#,nng_tcp_dialer_dial()>>|initiate outgoing TCP connection -|<<nng_tcp_dialer_free.3tcp#,nng_tcp_dialer_free()>>|free TCP dialer -|<<nng_tcp_dialer_getopt.3tcp#,nng_tcp_dialer_getopt()>>|get option from TCP dialer -|<<nng_tcp_dialer_setopt.3tcp#,nng_tcp_dialer_setopt()>>|set option on TCP dialer -|<<nng_tcp_free.3tcp#,nng_tcp_free()>>|free TCP connection -|<<nng_tcp_getopt.3tcp#,nng_tcp_getopt()>>|get option from TCP connection -|<<nng_tcp_listener_accept.3tcp#,nng_tcp_listener_accept()>>|accept incoming TCP connection -|<<nng_tcp_listener_alloc.3tcp#,nng_tcp_listener_alloc()>>|allocate TCP listener -|<<nng_tcp_listener_close.3tcp#,nng_tcp_listener_close()>>|close TCP listener -|<<nng_tcp_listener_free.3tcp#,nng_tcp_listener_free()>>|free TCP listener -|<<nng_tcp_listener_getopt.3tcp#,nng_tcp_listener_getopt()>>|get option from TCP listener -|<<nng_tcp_listener_listen.3tcp#,nng_tcp_listener_listen()>>|bind TCP listener to port -|<<nng_tcp_listener_setopt.3tcp#,nng_tcp_listener_setopt()>>|set option on TCP listener -|<<nng_tcp_recv.3tcp#,nng_tcp_recv()>>|receive from TCP connection -|<<nng_tcp_send.3tcp#,nng_tcp_send()>>|send to TCP connection -|<<nng_tcp_setopt.3tcp#,nng_tcp_setopt()>>|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. - -|=== -|<<nng_ipc_close.3ipc#,nng_ipc_close()>>|close IPC connection -|<<nng_ipc_dialer_alloc.3ipc#,nng_ipc_dialer_alloc()>>|allocate IPC dialer -|<<nng_ipc_dialer_close.3ipc#,nng_ipc_dialer_close()>>|close IPC dialer -|<<nng_ipc_dialer_dial.3ipc#,nng_ipc_dialer_dial()>>|initiate outgoing IPC connection -|<<nng_ipc_dialer_free.3ipc#,nng_ipc_dialer_free()>>|free IPC dialer -|<<nng_ipc_dialer_getopt.3ipc#,nng_ipc_dialer_getopt()>>|get option from IPC dialer -|<<nng_ipc_dialer_setopt.3ipc#,nng_ipc_dialer_setopt()>>|set option on IPC dialer -|<<nng_ipc_free.3ipc#,nng_ipc_free()>>|free IPC connection -|<<nng_ipc_getopt.3ipc#,nng_ipc_getopt()>>|get option from IPC connection -|<<nng_ipc_listener_accept.3ipc#,nng_ipc_listener_accept()>>|accept incoming IPC connection -|<<nng_ipc_listener_alloc.3ipc#,nng_ipc_listener_alloc()>>|allocate IPC listener -|<<nng_ipc_listener_close.3ipc#,nng_ipc_listener_close()>>|close IPC listener -|<<nng_ipc_listener_free.3ipc#,nng_ipc_listener_free()>>|free IPC listener -|<<nng_ipc_listener_getopt.3ipc#,nng_ipc_listener_getopt()>>|get option from IPC listener -|<<nng_ipc_listener_listen.3ipc#,nng_ipc_listener_listen()>>|bind IPC listener -|<<nng_ipc_listener_setopt.3ipc#,nng_ipc_listener_setopt()>>|set option on IPC listener -|<<nng_ipc_recv.3ipc#,nng_ipc_recv()>>|receive from IPC connection -|<<nng_ipc_send.3ipc#,nng_ipc_send()>>|send to IPC connection -|<<nng_ipc_setopt.3ipc#,nng_ipc_setopt()>>|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. |=== -|<<nng_http_conn_close.3http#,nng_http_conn_close()>>|close HTTP connection -|<<nng_http_conn_read.3http#,nng_http_conn_read()>>|read from HTTP connection -|<<nng_http_conn_read_all.3http#,nng_http_conn_read_all()>>|read all from HTTP connection -|<<nng_http_conn_read_req.3http#,nng_http_conn_read_req()>>|read HTTP request -|<<nng_http_conn_read_res.3http#,nng_http_conn_read_res()>>|read HTTP response -|<<nng_http_conn_write.3http#,nng_http_conn_write()>>|write to HTTP connection -|<<nng_http_conn_write_all.3http#,nng_http_conn_write_all()>>|write all to HTTP connection -|<<nng_http_conn_write_req.3http#,nng_http_conn_write_req()>>|write HTTP request -|<<nng_http_conn_write_res.3http#,nng_http_conn_write_res()>>|write HTTP response -|<<nng_http_req_add_header.3http#,nng_http_req_add_header()>>|add HTTP request header -|<<nng_http_req_alloc.3http#,nng_http_req_alloc()>>|allocate HTTP request structure -|<<nng_http_req_copy_data.3http#,nng_http_req_copy_data()>>|copy HTTP request body -|<<nng_http_req_del_header.3http#,nng_http_req_del_header()>>|delete HTTP request header -|<<nng_http_req_free.3http#,nng_http_req_free()>>|free HTTP request structure -|<<nng_http_req_get_data.3http#,nng_http_req_get_data()>>|get HTTP request body -|<<nng_http_req_get_header.3http#,nng_http_req_get_header()>>|return HTTP request header -|<<nng_http_req_get_method.3http#,nng_http_req_get_method()>>|return HTTP request method -|<<nng_http_req_get_uri.3http#,nng_http_req_get_uri()>>|return HTTP request URI -|<<nng_http_req_get_version.3http#,nng_http_req_get_version()>>|return HTTP request protocol version -|<<nng_http_req_reset.3http#,nng_http_req_reset()>>|reset HTTP request structure -|<<nng_http_req_set_data.3http#,nng_http_req_set_data()>>|set HTTP request body -|<<nng_http_req_set_header.3http#,nng_http_req_set_header()>>|set HTTP request header -|<<nng_http_req_set_method.3http#,nng_http_req_set_method()>>|set HTTP request method -|<<nng_http_req_set_uri.3http#,nng_http_req_set_uri()>>|set HTTP request URI -|<<nng_http_req_set_version.3http#,nng_http_req_set_version()>>|set HTTP request protocol version -|<<nng_http_res_add_header.3http#,nng_http_res_add_header()>>|add HTTP response header -|<<nng_http_res_alloc.3http#,nng_http_res_alloc()>>|allocate HTTP response structure -|<<nng_http_res_alloc_error.3http#,nng_http_res_alloc_error()>>|allocate HTTP error response -|<<nng_http_res_copy_data.3http#,nng_http_res_copy_data()>>|copy HTTP response body -|<<nng_http_res_del_header.3http#,nng_http_res_del_header()>>|delete HTTP response header -|<<nng_http_res_free.3http#,nng_http_res_free()>>|free HTTP response structure -|<<nng_http_res_get_data.3http#,nng_http_res_get_data()>>|get HTTP response body -|<<nng_http_res_get_header.3http#,nng_http_res_get_header()>>|return HTTP response header -|<<nng_http_res_get_reason.3http#,nng_http_res_get_reason()>>|return HTTP response reason -|<<nng_http_res_get_status.3http#,nng_http_res_get_status()>>|return HTTP response status -|<<nng_http_res_get_version.3http#,nng_http_res_get_version()>>|return HTTP response protocol version -|<<nng_http_res_reset.3http#,nng_http_res_reset()>>|reset HTTP response structure -|<<nng_http_res_set_data.3http#,nng_http_res_set_data()>>|set HTTP response body -|<<nng_http_res_set_header.3http#,nng_http_res_set_header()>>|set HTTP response header -|<<nng_http_res_set_reason.3http#,nng_http_res_set_reason()>>|set HTTP response reason -|<<nng_http_res_set_status.3http#,nng_http_res_set_status()>>|set HTTP response status -|<<nng_http_res_set_version.3http#,nng_http_res_set_version()>>|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. |=== -|<<nng_http_client_alloc.3http#,nng_http_client_alloc()>>|allocate HTTP client -|<<nng_http_client_connect.3http#,nng_http_client_connect()>>|establish HTTP client connection -|<<nng_http_client_free.3http#,nng_http_client_free()>>|free HTTP client -|<<nng_http_client_get_tls.3http#,nng_http_client_get_tls()>>|get HTTP client TLS configuration -|<<nng_http_client_set_tls.3http#,nng_http_client_set_tls()>>|set HTTP client TLS configuration -|<<nng_http_client_transact.3http#,nng_http_client_transact()>>|perform one HTTP transaction -|<<nng_http_conn_transact.3http#,nng_http_conn_transact()>>|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. |=== -|<<nng_http_handler_alloc.3http#,nng_http_handler_alloc()>>|allocate HTTP server handler -|<<nng_http_handler_collect_body.3http#,nng_http_handler_collect_body()>>|set HTTP handler to collect request body -|<<nng_http_handler_free.3http#,nng_http_handler_free()>>|free HTTP server handler -|<<nng_http_handler_get_data.3http#,nng_http_handler_get_data()>>|return extra data for HTTP handler -|<<nng_http_handler_set_data.3http#,nng_http_handler_set_data()>>|set extra data for HTTP handler -|<<nng_http_handler_set_host.3http#,nng_http_handler_set_host()>>|set host for HTTP handler -|<<nng_http_handler_set_method.3http#,nng_http_handler_set_method()>>|set HTTP handler method -|<<nng_http_handler_set_tree.3http#,nng_http_handler_set_tree()>>|set HTTP handler to match trees -|<<nng_http_hijack.3http#,nng_http_hijack()>>|hijack HTTP server connection -|<<nng_http_server_add_handler.3http#,nng_http_server_add_handler()>>|add HTTP server handler -|<<nng_http_server_del_handler.3http#,nng_http_server_del_handler()>>|delete HTTP server handler -|<<nng_http_server_get_tls.3http#,nng_http_server_get_tls()>>|get HTTP server TLS configuration -|<<nng_http_server_hold.3http#,nng_http_server_hold()>>|get and hold HTTP server instance -|<<nng_http_server_release.3http#,nng_http_server_release()>>|release HTTP server instance -|<<nng_http_server_set_error_file.3http#,nng_http_server_set_error_file()>>|set custom HTTP error file -|<<nng_http_server_set_error_page.3http#,nng_http_server_set_error_page()>>|set custom HTTP error page -|<<nng_http_server_set_tls.3http#,nng_http_server_set_tls()>>|set HTTP server TLS configuration -|<<nng_http_server_res_error.3http#,nng_http_server_res_error()>>|use HTTP server error page -|<<nng_http_server_start.3http#,nng_http_server_start()>>|start HTTP server -|<<nng_http_server_stop.3http#,nng_http_server_stop()>>|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. |=== -|<<nng_tls_close.3tls#,nng_tls_close()>>|close TLS connection -|<<nng_tls_config_alloc.3tls#,nng_tls_config_alloc()>>|allocate TLS configuration -|<<nng_tls_config_auth_mode.3tls#,nng_tls_config_auth_mode()>>|set authentication mode -|<<nng_tls_config_ca_chain.3tls#,nng_tls_config_ca_chain()>>|set certificate authority chain -|<<nng_tls_config_ca_file.3tls#,nng_tls_config_ca_file()>>|load certificate authority from file -|<<nng_tls_config_cert_key_file.3tls#,nng_tls_config_cert_key_file()>>|load own certificate and key from file -|<<nng_tls_config_own_cert.3tls#,nng_tls_config_own_cert()>>|set own certificate and key -|<<nng_tls_config_free.3tls#,nng_tls_config_free()>>|free TLS configuration -|<<nng_tls_config_server_name.3tls#,nng_tls_config_server_name()>>|set remote server name -|<<nng_tls_dialer_alloc.3tls#,nng_tls_dialer_alloc()>>|allocate TLS dialer -|<<nng_tls_dialer_close.3tls#,nng_tls_dialer_close()>>|close TLS dialer -|<<nng_tls_dialer_dial.3tls#,nng_tls_dialer_dial()>>|initiate outgoing TLS connection -|<<nng_tls_dialer_free.3tls#,nng_tls_dialer_free()>>|free TLS dialer -|<<nng_tls_dialer_getopt.3tls#,nng_tls_dialer_getopt()>>|get option from TLS dialer -|<<nng_tls_dialer_setopt.3tls#,nng_tls_dialer_setopt()>>|set option on TLS dialer -|<<nng_tls_free.3tls#,nng_tls_free()>>|free TLS connection -|<<nng_tls_getopt.3tls#,nng_tls_getopt()>>|get option from TLS connection -|<<nng_tls_listener_accept.3tls#,nng_tls_listener_accept()>>|accept incoming TLS connection -|<<nng_tls_listener_alloc.3tls#,nng_tls_listener_alloc()>>|allocate TLS listener -|<<nng_tls_listener_close.3tls#,nng_tls_listener_close()>>|close TLS listener -|<<nng_tls_listener_free.3tls#,nng_tls_listener_free()>>|free TLS listener -|<<nng_tls_listener_getopt.3tls#,nng_tls_listener_getopt()>>|get option from TLS listener -|<<nng_tls_listener_listen.3tls#,nng_tls_listener_listen()>>|bind TLS listener to port -|<<nng_tls_listener_setopt.3tls#,nng_tls_listener_setopt()>>|set option on TLS listener -|<<nng_tls_recv.3tls#,nng_tls_recv()>>|receive from TLS connection -|<<nng_tls_send.3tls#,nng_tls_send()>>|send to TLS connection -|<<nng_tls_setopt.3tls#,nng_tls_setopt()>>|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] -<<nng_compat.3compat#,nng_compat(3compat)>>, -<<nng.7#,nng(7)>> +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/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/man3ipc.sect b/docs/man/man3str.sect index ed1b8306..ed1b8306 100644 --- a/docs/man/man3ipc.sect +++ b/docs/man/man3str.sect 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 -<<nng_ipc.7#,nng_ipc(7)>> transport. - -TIP: Most NNG applications should not use this, but instead use the -<<nng_ipc.7#,nng_ipc(7)>> transport instead. - -These objects are created either establishing an outgoing connection -with <<nng_ipc_dialer_dial.3ipc#,`nng_ipc_dialer_dial()`>> or by -accepting in incoming connection with -<<nng_ipc_listener_accept.3ipc#,`nng_ipc_listener_accept()`>>. - -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 <<nng_ipc_send.3ipc#,`nng_ipc_send()`>> or -received with <<nng_ipc_recv.3ipc#,`nng_ipc_recv()`>>. - -When the connection is no longer needed, it should be freed with -<<nng_ipc_free.3ipc#,`nng_ipc_free()`>>. - -TIP: It is possible to close the connection, without freeing it, by -using <<nng_ipc_close.3ipc#,`nng_ipc_close()`>>. - -=== Options - -The following options are applicable to IPC connections, and may be -accessed using the <<nng_ipc_getopt.3ipc#,`nng_ipc_getopt()`>> and -<<nng_ipc_setopt.3ipc#,`nng_ipc_setopt()`>> functions. - -* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>> -* <<nng_options.5#NNG_OPT_REMADDR,`NNG_OPT_REMADDR`>> -* <<nng_ipc_options.5#NNG_OPT_IPC_PEER_GID,`NNG_OPT_IPC_PEER_GID`>> -* <<nng_ipc_options.5#NNG_OPT_IPC_PEER_PID,`NNG_OPT_IPC_PEER_PID`>> -* <<nng_ipc_options.5#NNG_OPT_IPC_PEER_UID,`NNG_OPT_IPC_PEER_UID`>> -* <<nng_ipc_options.5#NNG_OPT_IPC_PEER_ZONEID,`NNG_OPT_IPC_PEER_ZONEID`>> - -Other platform specific options may be available as well. - -== SEE ALSO - -[.text-left] -<<libnng.3#,libnng(3)>>, -<<nng_ipc_close.3ipc#,nng_ipc_close(3ipc)>>, -<<nng_ipc_dialer_dial.3ipc#,nng_ipc_dialer_dial(3ipc)>>, -<<nng_ipc_free.3ipc#,nng_ipc_free(3ipc)>>, -<<nng_ipc_getopt.3ipc#,nng_ipc_getopt(3ipc)>>, -<<nng_ipc_listener_accept.3ipc#,nng_ipc_listener_accept(3ipc)>>, -<<nng_ipc_recv.3ipc#,nng_ipc_recv(3ipc)>>, -<<nng_ipc_send.3ipc#,nng_ipc_send(3ipc)>>, -<<nng_ipc_setopt.3ipc#,nng_ipc_setopt(3ipc)>>, -<<nng_ipc_options.5#,nng_ipc_options(5)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng.7#,nng(7)>>, -<<nng_ipc.7#,nng_ipc(7)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 <<nng_ipc_send.3ipc#,`nng_ipc_send()`>> -or <<nng_ipc_recv.3ipc#,`nng_ipc_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 <<nng_ipc_free.3ipc#,`nng_ipc_free()`>>. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc_free.3ipc#,nng_ipc_free(3ipc)>>, -<<nng_ipc_recv.3ipc#,nng_ipc_recv(3ipc)>>, -<<nng_ipc_send.3ipc#,nng_ipc_send(3ipc)>>, -<<nng_ipc.5#,nng_ipc(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 (<<nng_ipc.5#,`nng_ipc`>> 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 -<<nng_ipc.7#,nng_ipc(7)>> transport. - -TIP: Most NNG applications should not use this, but instead use the -<<nng_ipc.7#,nng_ipc(7)>> transport instead. - -== SEE ALSO - -[.text-left] -<<nng_ipc_dialer_alloc.3ipc#,nng_ipc_dialer_alloc(3ipc)>>, -<<nng_ipc_dialer_close.3ipc#,nng_ipc_dialer_close(3ipc)>>, -<<nng_ipc_dialer_dial.3ipc#,nng_ipc_dialer_dial(3ipc)>>, -<<nng_ipc_dialer_free.3ipc#,nng_ipc_dialer_free(3ipc)>>, -<<nng_ipc.5#,nng_ipc(5)>>, -<<nng_ipc_options.5#,nng_ipc_options(5)>>, -<<nng_ipc_listener.5#,nng_ipc_listener(5)>>, -<<nng_ipc.7#,nng_ipc(7)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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] -<<nng_ipc_dialer_close.3ipc#,nng_ipc_dialer_close(3ipc)>>, -<<nng_ipc_dialer_dial.3ipc#,nng_ipc_dialer_dial(3ipc)>>, -<<nng_ipc_dialer_free.3ipc#,nng_ipc_dialer_free(3ipc)>>, -<<nng_ipc_dialer.5#,nng_ipc_dialer(5)>>, -<<nng_strerror.3#,nng_strerror(3)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 <<nng_ipc_dialer_dial.3ipc#,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 -<<nng_ipc_dialer_free.3ipc#,`nng_ipc_dialer_free(3ipc)`>> -once it is certain that nothing else is using it. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc_dialer_alloc.3ipc#,nng_ipc_dialer_alloc(3ipc)>>, -<<nng_ipc_dialer_dial.3ipc#,nng_ipc_dialer_dial(3ipc)>>, -<<nng_ipc_dialer_free.3ipc#,nng_ipc_dialer_free(3ipc)>>, -<<nng_ipc_dialer.5#,nng_ipc_dialer(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 <<nng_ipc.5#,`nng_ipc`>> stored as its first output. -(See <<nng_aio_get_output.3#,`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. -`NNG_EPERM`:: Insufficient permission to access the IPC path. - -== SEE ALSO - -[.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc_dialer_alloc.3ipc#,nng_ipc_dialer_alloc(3ipc)>>, -<<nng_ipc_dialer_close.3ipc#,nng_ipc_dialer_close(3ipc)>>, -<<nng_ipc_dialer_free.3ipc#,nng_ipc_dialer_free(3ipc)>>, -<<nng_aio.5#,nng_aio(5)>>, -<<nng_sockaddr.5#,nng_sockaddr(5)>>, -<<nng_ipc.5#,nng_ipc(5)>>, -<<nng_ipc_dialer.5#,nng_ipc_dialer(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 <<nng_ipc_dialer.5#,IPC dialer>> _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] -<<nng_ipc_dialer_setopt.3ipc#,nng_ipc_dialer_setopt(3ipc)>>, -<<nng_ipc_getopt.3ipc#,nng_ipc_getopt(3ipc)>>, -<<nng_ipc_options.5#,nng_ipc_options(5)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc.5#,nng_ipc(5)>>, -<<nng_ipc_dialer.5#,nng_ipc_dialer(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 -<<nng_ipc_dialer.5#,IPC dialer>> _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] -<<nng_ipc_dialer_getopt.3ipc#,nng_ipc_dialer_getopt(3ipc)>>, -<<nng_ipc_setopt.3ipc#,nng_ipc_setopt(3ipc)>>, -<<nng_ipc_options.5#,nng_ipc_options(5)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc.5#,nng_ipc(5)>>, -<<nng_ipc_dialer.5#,nng_ipc_dialer(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 <<nng_ipc_send.3ipc#,`nng_ipc_send()`>> -or <<nng_ipc_recv.3ipc#,`nng_ipc_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 _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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc_close.3ipc#,nng_ipc_close(3ipc)>>, -<<nng_ipc_recv.3ipc#,nng_ipc_recv(3ipc)>>, -<<nng_ipc_send.3ipc#,nng_ipc_send(3ipc)>>, -<<nng_ipc.5#,nng_ipc(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 <<nng_ipc.5#,IPC connection>> _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: - -* <<nng_ipc_options.5#NNG_OPT_IPC_PEER_GID,`NNG_OPT_IPC_PEER_GID`>> -* <<nng_ipc_options.5#NNG_OPT_IPC_PEER_PID,`NNG_OPT_IPC_PEER_PID`>> -* <<nng_ipc_options.5#NNG_OPT_IPC_PEER_UID,`NNG_OPT_IPC_PEER_UID`>> -* <<nng_ipc_options.5#NNG_OPT_IPC_PEER_ZONEID,`NNG_OPT_IPC_PEER_ZONEID`>> -* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>> -* <<nng_options.5#NNG_OPT_REMADDR,`NNG_OPT_REMADDR`>> - -== 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] -<<nng_ipc_setopt.3ipc#,nng_ipc_setopt(3ipc)>>, -<<nng_ipc_options.5#,nng_ipc_options(5)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc.5#,nng_ipc(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 (<<nng_ipc.5#,`nng_ipc`>> 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 -<<nng_ipc.7#,nng_ipc(7)>> transport. - -TIP: Most NNG applications should not use this, but instead use the -<<nng_ipc.7#,nng_ipc(7)>> transport instead. - -== SEE ALSO - -[.text-left] -<<nng_ipc_listener_accept.3ipc#,nng_ipc_listener_accept(3ipc)>>, -<<nng_ipc_listener_alloc.3ipc#,nng_ipc_listener_alloc(3ipc)>>, -<<nng_ipc_listener_close.3ipc#,nng_ipc_listener_close(3ipc)>>, -<<nng_ipc_listener_free.3ipc#,nng_ipc_listener_free(3ipc)>>, -<<nng_ipc_listener_listen.3ipc#,nng_ipc_listener_listen(3ipc)>>, -<<nng_ipc.5#,nng_ipc(5)>>, -<<nng_ipc_dialer.5#,nng_ipc_dialer(5)>>, -<<nng_ipc_options.5#,nng_ipc_options(5)>>, -<<nng_ipc.7#,nng_ipc(7)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 <<nng_ipc_listener_listen.3ipc#,listening>>. - -If a connection is successfully established, the _aio_ will have the -resulting <<nng_ipc.5#,`nng_ipc`>> stored as its first output. -(See <<nng_aio_get_output.3#,`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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc_listener_alloc.3ipc#,nng_ipc_listener_alloc(3ipc)>>, -<<nng_ipc_listener_close.3ipc#,nng_ipc_listener_close(3ipc)>>, -<<nng_ipc_listener_free.3ipc#,nng_ipc_listener_free(3ipc)>>, -<<nng_ipc_listener_listen.3ipc#,nng_ipc_listener_listen(3ipc)>>, -<<nng_aio.5#,nng_aio(5)>>, -<<nng_ipc.5#,nng_ipc(5)>>, -<<nng_ipc_listener.5#,nng_ipc_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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] -<<nng_ipc_listener_accept.3ipc#,nng_ipc_listener_accept(3ipc)>>, -<<nng_ipc_listener_close.3ipc#,nng_ipc_listener_close(3ipc)>>, -<<nng_ipc_listener_free.3ipc#,nng_ipc_listener_free(3ipc)>>, -<<nng_ipc_listener_listen.3ipc#,nng_ipc_listener_listen(3ipc)>>, -<<nng_ipc_listener.5#,nng_ipc_listener(5)>>, -<<nng_strerror.3#,nng_strerror(3)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 <<nng_ipc_listener_accept.3ipc#,accept>> 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 -<<nng_ipc_listener_free.3ipc#,`nng_ipc_listener_free()`>> -once it is certain that nothing else is using it. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc_listener_alloc.3ipc#,nng_ipc_listener_alloc(3ipc)>>, -<<nng_ipc_listener_accept.3ipc#,nng_ipc_listener_accept(3ipc)>>, -<<nng_ipc_listener_free.3ipc#,nng_ipc_listener_free(3ipc)>>, -<<nng_ipc_listener.5#,nng_ipc_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 <<nng_ipc_listener_accept.3ipc#,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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc_listener_alloc.3ipc#,nng_ipc_listener_alloc(3ipc)>>, -<<nng_ipc_listener_close.3ipc#,nng_ipc_listener_close(3ipc)>>, -<<nng_ipc_listener.5#,nng_ipc_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 <<nng_ipc_listener.5#,IPC listener>> _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: - -* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>> - -== 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] -<<nng_ipc_listener_setopt.3ipc#,nng_ipc_listener_setopt(3ipc)>>, -<<nng_ipc_getopt.3ipc#,nng_ipc_getopt(3ipc)>>, -<<nng_ipc_options.5#,nng_ipc_options(5)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc.5#,nng_ipc(5)>>, -<<nng_ipc_listener.5#,nng_ipc_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc_listener_accept.3ipc#,nng_ipc_listener_accept(3ipc)>>, -<<nng_ipc_listener_alloc.3ipc#,nng_ipc_listener_alloc(3ipc)>>, -<<nng_ipc_listener_close.3ipc#,nng_ipc_listener_close(3ipc)>>, -<<nng_ipc_listener_free.3ipc#,nng_ipc_listener_free(3ipc)>>, -<<nng_ipc_listener_getopt.3ipc#,nng_ipc_listener_getopt(3ipc)>>, -<<nng_sockaddr.5#,nng_sockaddr(5)>>, -<<nng_ipc_listener.5#,nng_ipc_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 -<<nng_ipc_listener.5#,IPC listener>> _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: - -* <<nng_ipc_options.5#NNG_OPT_IPC_PERMISSIONS,`NNG_OPT_IPC_PERMISSIONS`>> -* <<nng_ipc_options.5#NNG_OPT_IPC_SECURITY_DESCRIPTOR,`NNG_OPT_IPC_SECURITY_DESCRIPTOR`>> - -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] -<<nng_ipc_listener_getopt.3ipc#,nng_ipc_listener_getopt(3ipc)>>, -<<nng_ipc_setopt.3ipc#,nng_ipc_setopt(3ipc)>>, -<<nng_ipc_options.5#,nng_ipc_options(5)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc.5#,nng_ipc(5)>>, -<<nng_ipc_listener.5#,nng_ipc_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 <<nng_aio_set_iov.3#,`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 -<<nng_aio_result.3#,`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 -<<nng_aio_count.3#,`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] -<<nng_aio_alloc.3#,nng_aio_alloc(3)>>, -<<nng_aio_count.3#,nng_aio_count(3)>>, -<<nng_aio_result.3#,nng_aio_result(3)>>, -<<nng_aio_set_iov.3#,nng_aio_set_iov(3)>>, -<<nng_ipc_close.3ipc#,nng_ipc_close(3ipc)>>, -<<nng_ipc_send.3ipc#,nng_ipc_send(3ipc)>>, -<<nng_ipc.5#,nng_ipc(5)>>, -<<nng_strerror.3#,nng_strerror(3)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> - -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 -<<nng_ipc.5#,IPC connection>> _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] -<<nng_ipc_getopt.3ipc#,nng_ipc_getopt(3ipc)>>, -<<nng_ipc_options.5#,nng_ipc_options(5)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc.5#,nng_ipc(5)>> 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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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_tls_close.3tls.adoc b/docs/man/nng_stream_close.3str.adoc index 49836965..9e7b8d6a 100644 --- a/docs/man/nng_tls_close.3tls.adoc +++ b/docs/man/nng_stream_close.3str.adoc @@ -1,4 +1,4 @@ -= nng_tls_close(3tls) += nng_stream_close(3str) // // Copyright 2019 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> @@ -12,24 +12,27 @@ == NAME -nng_tls_close - close TLS connection +nng_stream_close - close byte stream == SYNOPSIS [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/tls/tls.h> -void nng_tls_close(nng_tls *conn); +void nng_stream_close(nng_stream *s); ---- == DESCRIPTION -The `nng_tls_close()` function closes the supplied TLS connection, _conn_. +The `nng_stream_close()` function closes the +xref:nng_stream.5.adoc[byte stream] _s_. -If any operations are pending (such as <<nng_tls_send.3tls#,`nng_tls_send()`>> -or <<nng_tls_recv.3tls#,`nng_tls_recv()`>> they will be terminated with +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. @@ -41,7 +44,8 @@ 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 <<nng_tls_free.3tls#,`nng_tls_free()`>>. +it should be freed with +xref:nng_stream_free.3str.adoc[`nng_stream_free()`]. == RETURN VALUES @@ -54,8 +58,8 @@ None. == SEE ALSO [.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_free.3tls#,nng_tls_free(3tls)>>, -<<nng_tls_recv.3tls#,nng_tls_recv(3tls)>>, -<<nng_tls_send.3tls#,nng_tls_send(3tls)>>, -<<nng_tls.5#,nng_tls(5)>> +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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_tls_dialer_close.3tls.adoc b/docs/man/nng_stream_dialer_close.3str.adoc index 19ca0bd1..59d9dec0 100644 --- a/docs/man/nng_tls_dialer_close.3tls.adoc +++ b/docs/man/nng_stream_dialer_close.3str.adoc @@ -1,6 +1,6 @@ -= nng_tls_dialer_close(3tls) += nng_stream_dialer_close(3str) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // Copyright 2019 Devolutions <info@devolutions.net> // @@ -12,24 +12,26 @@ == NAME -nng_tls_dialer_close - close TLS dialer +nng_stream_dialer_close - close byte stream dialer == SYNOPSIS [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/tls/tls.h> -void nng_tls_dialer_close(nng_tls_dialer *d); +void nng_stream_dialer_close(nng_stream_dialer *d); ---- == DESCRIPTION -The `nng_tls_dialer_close()` function closes the supplied TCP dialer _d_, +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 <<nng_tls_dialer_dial.3tls#,dial>> operations using _d_ are +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 @@ -37,7 +39,7 @@ Furthermore any future accesses to the dialer _d_ will also result in NOTE: This function does not release the memory for the dialer, so the application should still free the memory using -<<nng_tls_dialer_free.3tls#,`nng_tls_dialer_free()`>> +xref:nng_stream_dialer_free.3str.adoc[`nng_stream_dialer_free()`] once it is certain that nothing else is using it. == RETURN VALUES @@ -51,8 +53,8 @@ None. == SEE ALSO [.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_dialer_alloc.3tls#,nng_tls_dialer_alloc(3tls)>>, -<<nng_tls_dialer_dial.3tls#,nng_tls_dialer_dial(3tls)>>, -<<nng_tls_dialer_free.3tls#,nng_tls_dialer_free(3tls)>>, -<<nng_tls_dialer.5#,nng_tls_dialer(5)>> +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_tls_dialer_dial.3tls.adoc b/docs/man/nng_stream_dialer_dial.3str.adoc index 31d9036d..cc4c55de 100644 --- a/docs/man/nng_tls_dialer_dial.3tls.adoc +++ b/docs/man/nng_stream_dialer_dial.3str.adoc @@ -1,4 +1,4 @@ -= nng_tls_dialer_dial(3tls) += nng_stream_dialer_dial(3str) // // Copyright 2019 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> @@ -12,30 +12,32 @@ == NAME -nng_tls_dialer_dial - initiate outgoing TLS connection +nng_stream_dialer_dial - initiate outgoing byte stream connection == SYNOPSIS [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/tls/tls.h> -void nng_tls_dialer_dial(nng_tls_dialer *d, const nng_sockaddr *sa, nng_aio *aio); +void nng_stream_dialer_dial(nng_stream_dialer *d, 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 `nng_stream_dialer_dial()` attempts to establish a connection to the +remote peer for 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. +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 <<nng_tls.5#,`nng_tls`>> stored as its first output. -(See <<nng_aio_get_output.3#,`nng_aio_get_output()`>>.) +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 @@ -49,17 +51,15 @@ None. `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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_dialer_alloc.3tls#,nng_tls_dialer_alloc(3tls)>>, -<<nng_tls_dialer_close.3tls#,nng_tls_dialer_close(3tls)>>, -<<nng_tls_dialer_free.3tls#,nng_tls_dialer_free(3tls)>>, -<<nng_aio.5#,nng_aio(5)>>, -<<nng_sockaddr.5#,nng_sockaddr(5)>>, -<<nng_tls.5#,nng_tls(5)>>, -<<nng_tls_dialer.5#,nng_tls_dialer(5)>> +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_tls_dialer_free.3tls.adoc b/docs/man/nng_stream_dialer_free.3str.adoc index b5e7b2bf..6669ca1e 100644 --- a/docs/man/nng_tls_dialer_free.3tls.adoc +++ b/docs/man/nng_stream_dialer_free.3str.adoc @@ -1,9 +1,9 @@ -= nng_tls_dialer_free(3tls) += nng_stream_dialer_free(3str) // // Copyright 2019 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // Copyright 2019 Devolutions <info@devolutions.net> -// + // 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 @@ -12,24 +12,25 @@ == NAME -nng_tls_dialer_free - free TLS dialer +nng_stream_dialer_free - free byte stream dialer == SYNOPSIS [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/tls/tls.h> -void nng_tls_dialer_free(nng_tls_dialer *d); +void nng_stream_dialer_free(nng_stream_dialer *d); ---- == DESCRIPTION -The `nng_tls_dialer_free()` function closes the supplied TLS dialer _d_, +The `nng_stream_dialer_free()` function closes the supplied +byte stream dialer _d_, and frees the underlying resources associated with it. -If any <<nng_tls_dialer_dial.3tls#,dial>> operations using _d_ are +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 @@ -46,8 +47,8 @@ None. == SEE ALSO [.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_dialer_alloc.3tls#,nng_tls_dialer_alloc(3tls)>>, -<<nng_tls_dialer_close.3tls#,nng_tls_dialer_close(3tls)>>, -<<nng_tls_dialer_dial.3tls#,nng_tls_dialer_dial(3tls)>>, -<<nng_tls_dialer.5#,nng_tls_dialer(5)>> +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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_tls_free.3tls.adoc b/docs/man/nng_stream_free.3str.adoc index 62c2a81d..30679458 100644 --- a/docs/man/nng_tls_free.3tls.adoc +++ b/docs/man/nng_stream_free.3str.adoc @@ -1,4 +1,4 @@ -= nng_tls_free(3tls) += nng_stream_free(3str) // // Copyright 2019 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> @@ -12,29 +12,31 @@ == NAME -nng_tls_free - free TLS connection +nng_stream_free - free byte stream == SYNOPSIS [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/tls/tls.h> -void nng_tls_free(nng_tls *conn); +void nng_stream_free(nng_stream *s); ---- == DESCRIPTION -The `nng_tls_free()` function closes the supplied TLS connection, _conn_, +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 <<nng_tls_send.3tls#,`nng_tls_send()`>> -or <<nng_tls_recv.3tls#,`nng_tls_recv()`>> they will be terminated with -an `NNG_ECLOSED` error condition. +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 _conn_, as the memory backing it will be reclaimed for other uses. +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. @@ -52,8 +54,8 @@ None. == SEE ALSO [.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_close.3tls#,nng_tls_close(3tls)>>, -<<nng_tls_recv.3tls#,nng_tls_recv(3tls)>>, -<<nng_tls_send.3tls#,nng_tls_send(3tls)>>, -<<nng_tls.5#,nng_tls(5)>> +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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_tls_listener_close.3tls.adoc b/docs/man/nng_stream_listener_close.3str.adoc index 26120cee..a810509e 100644 --- a/docs/man/nng_tls_listener_close.3tls.adoc +++ b/docs/man/nng_stream_listener_close.3str.adoc @@ -1,4 +1,4 @@ -= nng_tls_listener_close(3tls) += nng_stream_listener_close(3str) // // Copyright 2019 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> @@ -12,32 +12,34 @@ == NAME -nng_tls_listener_close - close TLS listener +nng_stream_listener_close - close byte stream listener == SYNOPSIS [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/tls/tls.h> -void nng_tls_listener_close(nng_tls_listener *l); +void nng_stream_listener_close(nng_stream_listener *l); ---- == DESCRIPTION -The `nng_tls_listener_close()` function closes the supplied TLS listener _l_, +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 <<nng_tls_listener_accept.3tls#,accept>> operations using _l_ -are in progress, they will be terminated with an `NNG_ECLOSED` error condition. +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 -<<nng_tls_listener_free.3tls#,`nng_tls_listener_free()`>> +xref:nng_stream_listener_free.3str.adoc[`nng_stream_listener_free()`] once it is certain that nothing else is using it. == RETURN VALUES @@ -51,8 +53,8 @@ None. == SEE ALSO [.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_listener_alloc.3tls#,nng_tls_listener_alloc(3tls)>>, -<<nng_tls_listener_accept.3tls#,nng_tls_listener_accept(3tls)>>, -<<nng_tls_listener_free.3tls#,nng_tls_listener_free(3tls)>>, -<<nng_tls_listener.5#,nng_tls_listener(5)>> +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_ipc_dialer_free.3ipc.adoc b/docs/man/nng_stream_listener_free.3str.adoc index ff2bf025..aecd8895 100644 --- a/docs/man/nng_ipc_dialer_free.3ipc.adoc +++ b/docs/man/nng_stream_listener_free.3str.adoc @@ -1,9 +1,9 @@ -= nng_ipc_dialer_free(3ipc) += nng_stream_listener_free(3str) // // Copyright 2019 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // Copyright 2019 Devolutions <info@devolutions.net> -// + // 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 @@ -12,29 +12,29 @@ == NAME -nng_ipc_dialer_free - free IPC dialer +nng_stream_listener_free - free byte stream listener == SYNOPSIS [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> -void nng_ipc_dialer_free(nng_ipc_dialer *d); +void nng_stream_listener_free(nng_stream_listener *)l; ---- == DESCRIPTION -The `nng_ipc_dialer_free()` function closes the supplied IPC dialer _d_, +The `nng_stream_listener_free()` function closes the supplied +byte stream listener _l_, and frees the underlying resources associated with it. -If any <<nng_ipc_dialer_dial.3ipc#,dial>> operations - using _d_ are +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 _d_, as the memory backing it will be reclaimed for other uses. +are made to _l_, as the memory backing it will be reclaimed for other uses. == RETURN VALUES @@ -47,8 +47,8 @@ None. == SEE ALSO [.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_ipc_dialer_alloc.3ipc#,nng_ipc_dialer_alloc(3ipc)>>, -<<nng_ipc_dialer_close.3ipc#,nng_ipc_dialer_close(3ipc)>>, -<<nng_ipc_dialer_dial.3ipc#,nng_ipc_dialer_dial(3ipc)>>, -<<nng_ipc_dialer.5#,nng_ipc_dialer(5)>> +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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_tcp_recv.3tcp.adoc b/docs/man/nng_stream_recv.3str.adoc index 787ebfd3..3acb1921 100644 --- a/docs/man/nng_tcp_recv.3tcp.adoc +++ b/docs/man/nng_stream_recv.3str.adoc @@ -1,7 +1,8 @@ -= nng_tcp_recv(3tcp) += nng_stream_send(3str) // // Copyright 2019 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> // // This document is supplied under the terms of the MIT License, a // copy of which should be located in the distribution where this @@ -11,41 +12,39 @@ == NAME -nng_tcp_recv - receive from TCP connection +nng_stream_send - receive from byte stream == SYNOPSIS [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> -void nng_tcp_recv(nng_tcp *conn, nng_aio *aio); +void nng_stream_send(nng_stream *s, 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 +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 <<nng_aio_set_iov.3#,`nng_aio_set_iov()`>> function must have been +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 -<<nng_aio_result.3#,`nng_aio_result()`>>. +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 -<<nng_aio_count.3#,`nng_aio_count()`>>. - -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. +xref:nng_aio_count.3.adoc[`nng_aio_count()`]. == RETURN VALUES @@ -64,11 +63,11 @@ None. == SEE ALSO [.text-left] -<<nng_aio_alloc.3#,nng_aio_alloc(3)>>, -<<nng_aio_count.3#,nng_aio_count(3)>>, -<<nng_aio_result.3#,nng_aio_result(3)>>, -<<nng_aio_set_iov.3#,nng_aio_set_iov(3)>>, -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_close.3tcp#,nng_tcp_close(3tcp)>>, -<<nng_tcp_send.3tcp#,nng_tcp_send(3tcp)>>, -<<nng_tcp.5#,nng_tcp(5)>> +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_ipc_send.3ipc.adoc b/docs/man/nng_stream_send.3str.adoc index d606ddd9..2ae7355a 100644 --- a/docs/man/nng_ipc_send.3ipc.adoc +++ b/docs/man/nng_stream_send.3str.adoc @@ -1,6 +1,6 @@ -= nng_ipc_send(3ipc) += nng_stream_send(3str) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // Copyright 2019 Devolutions <info@devolutions.net> // @@ -12,37 +12,40 @@ == NAME -nng_ipc_send - send to IPC connection +nng_stream_send - send to byte stream == SYNOPSIS [source, c] ---- #include <nng/nng.h> -#include <nng/supplemental/ipc/ipc.h> -void nng_ipc_send(nng_ipc *conn, nng_aio *aio); +void nng_stream_send(nng_stream *s, 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 +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 <<nng_aio_set_iov.3#,`nng_aio_set_iov()`>> function must have been +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 <<nng_aio_result.3#,`nng_aio_result()`>>. +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 -<<nng_aio_count.3#,`nng_aio_count()`>>. +xref:nng_aio_count.3.adoc[`nng_aio_count()`]. == RETURN VALUES @@ -61,11 +64,11 @@ None. == SEE ALSO [.text-left] -<<nng_aio_alloc.3#,nng_aio_alloc(3)>>, -<<nng_aio_count.3#,nng_aio_count(3)>>, -<<nng_aio_result.3#,nng_aio_result(3)>>, -<<nng_aio_set_iov.3#,nng_aio_set_iov(3)>>, -<<nng_ipc_close.3ipc#,nng_ipc_close(3ipc)>>, -<<nng_ipc_recv.3ipc#,nng_ipc_recv(3ipc)>>, -<<nng_ipc.5#,nng_ipc(5)>>, -<<nng_strerror.3#,nng_strerror(3)>> +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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// Copyright 2019 Devolutions <info@devolutions.net> +// +// 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 <nng/nng.h> + +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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 <<nng_tcp_send.3tcp#,`nng_tcp_send()`>> -or <<nng_tcp_recv.3tcp#,`nng_tcp_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 <<nng_tcp_free.3tcp#,`nng_tcp_free()`>>. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_free.3tcp#,nng_tcp_free(3tcp)>>, -<<nng_tcp_recv.3tcp#,nng_tcp_recv(3tcp)>>, -<<nng_tcp_send.3tcp#,nng_tcp_send(3tcp)>>, -<<nng_tcp.5#,nng_tcp(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 (<<nng_tcp.5#,`nng_tcp`>> 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 -<<nng_tcp.7#,nng_tcp(7)>> transport. - -TIP: Most NNG applications should not use this, but instead use the -<<nng_tcp.7#,`nng_tcp`>> transport instead. - -== SEE ALSO - -[.text-left] -<<nng_tcp_dialer_alloc.3tcp#,nng_tcp_dialer_alloc(3tcp)>>, -<<nng_tcp_dialer_close.3tcp#,nng_tcp_dialer_close(3tcp)>>, -<<nng_tcp_dialer_dial.3tcp#,nng_tcp_dialer_dial(3tcp)>>, -<<nng_tcp_dialer_free.3tcp#,nng_tcp_dialer_free(3tcp)>>, -<<nng_tcp.5#,nng_tcp(5)>>, -<<nng_tcp_listener.5#,nng_tcp_listener(5)>>, -<<nng_tcp.7#,nng_tcp(7)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_dialer_close.3tcp#,nng_tcp_dialer_close(3tcp)>>, -<<nng_tcp_dialer_dial.3tcp#,nng_tcp_dialer_dial(3tcp)>>, -<<nng_tcp_dialer_free.3tcp#,nng_tcp_dialer_free(3tcp)>>, -<<nng_tcp_dialer_getopt.3tcp#,nng_tcp_dialer_getopt(3tcp)>>, -<<nng_tcp_dialer_setopt.3tcp#,nng_tcp_dialer_setopt(3tcp)>>, -<<nng_tcp_dialer.5#,nng_tcp_dialer(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 <<nng_tcp_dialer_dial.3tcp#,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 -<<nng_tcp_dialer_free.3tcp#,`nng_tcp_dialer_free()`>> -once it is certain that nothing else is using it. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_dialer_alloc.3tcp#,nng_tcp_dialer_alloc(3tcp)>>, -<<nng_tcp_dialer_dial.3tcp#,nng_tcp_dialer_dial(3tcp)>>, -<<nng_tcp_dialer_free.3tcp#,nng_tcp_dialer_free(3tcp)>>, -<<nng_tcp_dialer.5#,nng_tcp_dialer(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 <<nng_tcp.5#,`nng_tcp`>> stored as its first output. -(See <<nng_aio_get_output.3#,`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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_dialer_alloc.3tcp#,nng_tcp_dialer_alloc(3tcp)>>, -<<nng_tcp_dialer_close.3tcp#,nng_tcp_dialer_close(3tcp)>>, -<<nng_tcp_dialer_free.3tcp#,nng_tcp_dialer_free(3tcp)>>, -<<nng_aio.5#,nng_aio(5)>>, -<<nng_sockaddr.5#,nng_sockaddr(5)>>, -<<nng_tcp.5#,nng_tcp(5)>>, -<<nng_tcp_dialer.5#,nng_tcp_dialer(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 <<nng_tcp_dialer_dial.3tcp#,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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_dialer_alloc.3tcp#,nng_tcp_dialer_alloc(3tcp)>>, -<<nng_tcp_dialer_close.3tcp#,nng_tcp_dialer_close(3tcp)>>, -<<nng_tcp_dialer_dial.3tcp#,nng_tcp_dialer_dial(3tcp)>>, -<<nng_tcp_dialer.5#,nng_tcp_dialer(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 <<nng_tcp_dialer.5#,TCP dialer>> _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: - -* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>> - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_dialer_setopt.3tcp#,nng_tcp_dialer_setopt(3tcp)>>, -<<nng_tcp_getopt.3tcp#,nng_tcp_getopt(3tcp)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tcp_options.5#,nng_tcp_options(5)>>, -<<nng_tcp.5#,nng_tcp(5)>>, -<<nng_tcp_dialer.5#,nng_tcp_dialer(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 -<<nng_tcp_dialer.5#,TCP dialer>> _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: - -* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>> - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_dialer_getopt.3tcp#,nng_tcp_dialer_getopt(3tcp)>>, -<<nng_tcp_setopt.3tcp#,nng_tcp_setopt(3tcp)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tcp_options.5#,nng_tcp_options(5)>>, -<<nng_tcp.5#,nng_tcp(5)>>, -<<nng_tcp_dialer.5#,nng_tcp_dialer(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 <<nng_tcp_send.3tcp#,`nng_tcp_send()`>> -or <<nng_tcp_recv.3tcp#,`nng_tcp_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 _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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_close.3tcp#,nng_tcp_close(3tcp)>>, -<<nng_tcp_recv.3tcp#,nng_tcp_recv(3tcp)>>, -<<nng_tcp_send.3tcp#,nng_tcp_send(3tcp)>>, -<<nng_tcp.5#,nng_tcp(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 <<nng_tcp.5#,TCP connection>> _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: - -* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>> -* <<nng_options.5#NNG_OPT_REMADDR,`NNG_OPT_REMADDR`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>> - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_setopt.3tcp#,nng_tcp_setopt(3tcp)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tcp_options.5#,nng_tcp_options(5)>>, -<<nng_tcp.5#,nng_tcp(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 (<<nng_tcp.5#,`nng_tcp`>> 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 -<<nng_tcp.7#,nng_tcp(7)>> transport. - -TIP: Most NNG applications should not use this, but instead use the -<<nng_tcp.7#,nng_tcp(7)>> transport instead. - -== SEE ALSO - -[.text-left] -<<nng_tcp_listener_accept.3tcp#,nng_tcp_listener_accept(3tcp)>>, -<<nng_tcp_listener_alloc.3tcp#,nng_tcp_listener_alloc(3tcp)>>, -<<nng_tcp_listener_close.3tcp#,nng_tcp_listener_close(3tcp)>>, -<<nng_tcp_listener_free.3tcp#,nng_tcp_listener_free(3tcp)>>, -<<nng_tcp_listener_getopt.3tcp#,nng_tcp_listener_getopt(3tcp)>>, -<<nng_tcp_listener_listen.3tcp#,nng_tcp_listener_listen(3tcp)>>, -<<nng_tcp_listener_setopt.3tcp#,nng_tcp_listener_setopt(3tcp)>>, -<<nng_tcp.5#,nng_tcp(5)>>, -<<nng_tcp_dialer.5#,nng_tcp_dialer(5)>>, -<<nng_tcp.7#,nng_tcp(7)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 <<nng_tcp_listener_listen.3tcp#,listening>>. - -If a connection is successfully established, the _aio_ will have the -resulting <<nng_tcp.5#,`nng_tcp`>> stored as its first output. -(See <<nng_aio_get_output.3#,`nng_aio_get_output()`>>.) - -The address of the remote peer can be determined using the -<<nng_options.5#NNG_OPT_REMADDR,`NNG_OPT_REMADDR`>> option with the -<<nng_tcp_getopt.3tcp#,`nng_tcp_getopt()`>> function on the -returned <<nng_tcp.5#,`nng_tcp`>>. - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_listener_alloc.3tcp#,nng_tcp_listener_alloc(3tcp)>>, -<<nng_tcp_listener_close.3tcp#,nng_tcp_listener_close(3tcp)>>, -<<nng_tcp_listener_free.3tcp#,nng_tcp_listener_free(3tcp)>>, -<<nng_tcp_listener_listen.3tcp#,nng_tcp_listener_listen(3tcp)>>, -<<nng_aio.5#,nng_aio(5)>>, -<<nng_tcp.5#,nng_tcp(5)>>, -<<nng_tcp_listener.5#,nng_tcp_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_listener_accept.3tcp#,nng_tcp_listener_accept(3tcp)>>, -<<nng_tcp_listener_close.3tcp#,nng_tcp_listener_close(3tcp)>>, -<<nng_tcp_listener_free.3tcp#,nng_tcp_listener_free(3tcp)>>, -<<nng_tcp_listener_getopt.3tcp#,nng_tcp_listener_getopt(3tcp)>>, -<<nng_tcp_listener_listen.3tcp#,nng_tcp_listener_listen(3tcp)>>, -<<nng_tcp_listener_setopt.3tcp#,nng_tcp_listener_setopt(3tcp)>>, -<<nng_tcp_listener.5#,nng_tcp_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 <<nng_tcp_listener_accept.3tcp#,accept>> 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 -<<nng_tcp_listener_free.3tcp#,`nng_tcp_listener_free()`>> -once it is certain that nothing else is using it. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_listener_alloc.3tcp#,nng_tcp_listener_alloc(3tcp)>>, -<<nng_tcp_listener_accept.3tcp#,nng_tcp_listener_accept(3tcp)>>, -<<nng_tcp_listener_free.3tcp#,nng_tcp_listener_free(3tcp)>>, -<<nng_tcp_listener.5#,nng_tcp_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 <<nng_tcp_listener_accept.3tcp#,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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_listener_alloc.3tcp#,nng_tcp_listener_alloc(3tcp)>>, -<<nng_tcp_listener_close.3tcp#,nng_tcp_listener_close(3tcp)>>, -<<nng_tcp_listener.5#,nng_tcp_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 <<nng_tcp_listener.5#,TCP listener>> _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: - -* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>> - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_listener_setopt.3tcp#,nng_tcp_listener_setopt(3tcp)>>, -<<nng_tcp_getopt.3tcp#,nng_tcp_getopt(3tcp)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tcp.5#,nng_tcp(5)>>, -<<nng_tcp_listener.5#,nng_tcp_listener(5)>>, -<<nng_tcp_options.5#,nng_tcp_options(5)>> - 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 -<<nng_options.5#,`NNG_OPT_LOCADDR`>> option with the -<<nng_tcp_listener_getopt.3tcp#,`nng_tcp_listener_getopt()`>> 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_listener_accept.3tcp#,nng_tcp_listener_accept(3tcp)>>, -<<nng_tcp_listener_alloc.3tcp#,nng_tcp_listener_alloc(3tcp)>>, -<<nng_tcp_listener_close.3tcp#,nng_tcp_listener_close(3tcp)>>, -<<nng_tcp_listener_free.3tcp#,nng_tcp_listener_free(3tcp)>>, -<<nng_tcp_listener_getopt.3tcp#,nng_tcp_listener_getopt(3tcp)>>, -<<nng_sockaddr.5#,nng_sockaddr(5)>>, -<<nng_tcp_listener.5#,nng_tcp_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 -<<nng_tcp_listener.5#,TCP listener>> _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: - -* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>> - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp_listener_getopt.3tcp#,nng_tcp_listener_getopt(3tcp)>>, -<<nng_tcp_setopt.3tcp#,nng_tcp_setopt(3tcp)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tcp.5#,nng_tcp(5)>>, -<<nng_tcp_listener.5#,nng_tcp_listener(5)>>, -<<nng_tcp_options.5#,nng_tcp_options(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 <<nng_aio_set_iov.3#,`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 <<nng_aio_result.3#,`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 -<<nng_aio_count.3#,`nng_aio_count()`>>. - -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] -<<nng_aio_alloc.3#,nng_aio_alloc(3)>>, -<<nng_aio_count.3#,nng_aio_count(3)>>, -<<nng_aio_result.3#,nng_aio_result(3)>>, -<<nng_aio_set_iov.3#,nng_aio_set_iov(3)>>, -<<nng_tcp_close.3tcp#,nng_tcp_close(3tcp)>>, -<<nng_tcp_recv.3tcp#,nng_tcp_recv(3tcp)>>, -<<nng_tcp.5#,nng_tcp(5)>>, -<<nng_strerror.3#,nng_strerror(3)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tcp/tcp.h> - -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 -<<nng_tcp.5#,TCP connection>> _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: - -* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>> - -== 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] -<<nng_tcp_getopt.3tcp#,nng_tcp_getopt(3tcp)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tcp_options.5#,nng_tcp_options(5)>>, -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tcp.5#,nng_tcp(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 (<<nng_tls.5#,`nng_tls`>> 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 -<<nng_tls.7#,nng_tls(7)>> transport. - -TIP: Most NNG applications should not use this, but instead use the -<<nng_tls.7#,nng_tls(7)>> transport instead. - -== SEE ALSO - -[.text-left] -<<nng_tls_dialer_alloc.3tls#,nng_tls_dialer_alloc(3tls)>>, -<<nng_tls_dialer_close.3tls#,nng_tls_dialer_close(3tls)>>, -<<nng_tls_dialer_dial.3tls#,nng_tls_dialer_dial(3tls)>>, -<<nng_tls_dialer_free.3tls#,nng_tls_dialer_free(3tls)>>, -<<nng_tls.5#,nng_tls(5)>>, -<<nng_tls_listener.5#,nng_tls_listener(5)>>, -<<nng_tls_options.5#,nng_tls_options(5)>>, -<<nng_tls.7#,nng_tls(7)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_dialer_close.3tls#,nng_tls_dialer_close(3tls)>>, -<<nng_tls_dialer_dial.3tls#,nng_tls_dialer_dial(3tls)>>, -<<nng_tls_dialer_free.3tls#,nng_tls_dialer_free(3tls)>>, -<<nng_tls_dialer_getopt.3tls#,nng_tls_dialer_getopt(3tls)>>, -<<nng_tls_dialer_setopt.3tls#,nng_tls_dialer_setopt(3tls)>>, -<<nng_tls_dialer.5#,nng_tls_dialer(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 <<nng_tls_dialer.5#,TLS dialer>> _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: - -* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>> -* <<nng_tls_options.5#NNG_OPT_TLS_CONFIG,`NNG_OPT_TLS_CONFIG`>> - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_dialer_setopt.3tls#,nng_tls_dialer_setopt(3tls)>>, -<<nng_tls_getopt.3tls#,nng_tls_getopt(3tls)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tcp_options.5#,nng_tcp_options(5)>>, -<<nng_tls.5#,nng_tls(5)>>, -<<nng_tls_config.5#,nng_tls_config(5)>>, -<<nng_tls_dialer.5#,nng_tls_dialer(5)>>, -<<nng_tls_options.5#,nng_tls_options(5)>> - 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 -<<nng_tls_dialer.5#,TLS dialer>> _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: - -* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>> -* <<nng_tls_options.5#NNG_OPT_TLS_AUTH_MODE,`NNG_OPT_TLS_AUTH_MODE`>> -* <<nng_tls_options.5#NNG_OPT_TLS_CA_FILE,`NNG_OPT_TLS_CA_FILE`>> -* <<nng_tls_options.5#NNG_OPT_TLS_CERT_KEY_FILE,`NNG_OPT_TLS_CERT_KEY_FILE`>> -* <<nng_tls_options.5#NNG_OPT_TLS_CONFIG,`NNG_OPT_TLS_CONFIG`>> -* <<nng_tls_options.5#NNG_OPT_TLS_SERVER_NAME,`NNG_OPT_TLS_SERVER_NAME`>> - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_dialer_getopt.3tls#,nng_tls_dialer_getopt(3tls)>>, -<<nng_tls_setopt.3tls#,nng_tls_setopt(3tls)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tcp_options.5#,nng_tcp_options(5)>>, -<<nng_tls.5#,nng_tls(5)>>, -<<nng_tls_dialer.5#,nng_tls_dialer(5)>>, -<<nng_tls_options.5#,nng_tls_options(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 <<nng_tls.5#,TLS connection>> _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: - -* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>> -* <<nng_options.5#NNG_OPT_REMADDR,`NNG_OPT_REMADDR`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>> -* <<nng_tls_options.5#NNG_OPT_TLS_VERIFIED,`NNG_OPT_TLS_VERIFIED`>> - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_setopt.3tls#,nng_tls_setopt(3tls)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tcp_options.5#,nng_tcp_options(5)>>, -<<nng_tls.5#,nng_tlsp(5)>>, -<<nng_tls_options.5#,nng_tls_options(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 (<<nng_tls.5#,`nng_tls`>> 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 -<<nng_tls.7#,nng_tls(7)>> transport. - -TIP: Most NNG applications should not use this, but instead use the -<<nng_tls.7#,nng_tls(7)>> transport instead. - -== SEE ALSO - -[.text-left] -<<nng_tls_listener_accept.3tls#,nng_tls_listener_accept(3tls)>>, -<<nng_tls_listener_alloc.3tls#,nng_tls_listener_alloc(3tls)>>, -<<nng_tls_listener_close.3tls#,nng_tls_listener_close(3tls)>>, -<<nng_tls_listener_free.3tls#,nng_tls_listener_free(3tls)>>, -<<nng_tls_listener_getopt.3tls#,nng_tls_listener_getopt(3tls)>>, -<<nng_tls_listener_listen.3tls#,nng_tls_listener_listen(3tls)>>, -<<nng_tls_listener_setopt.3tls#,nng_tls_listener_setopt(3tls)>>, -<<nng_tls.5#,nng_tls(5)>>, -<<nng_tls_dialer.5#,nng_tls_dialer(5)>>, -<<nng_tls.7#,nng_tls(7)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 <<nng_tls_listener_listen.3tls#,listening>>. - -If a connection is successfully established, the _aio_ will have the -resulting <<nng_tls.5#,`nng_tls`>> stored as its first output. -(See <<nng_aio_get_output.3#,`nng_aio_get_output()`>>.) - -The address of the remote peer can be determined using the -<<nng_options.5#NNG_OPT_REMADDR,`NNG_OPT_REMADDR`>> option with the -<<nng_tls_getopt.3tls#,`nng_tls_getopt()`>> function on the -returned <<nng_tls.5#,`nng_tls`>>. - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_listener_alloc.3tls#,nng_tls_listener_alloc(3tls)>>, -<<nng_tls_listener_close.3tls#,nng_tls_listener_close(3tls)>>, -<<nng_tls_listener_free.3tls#,nng_tls_listener_free(3tls)>>, -<<nng_tls_listener_listen.3tls#,nng_tls_listener_listen(3tls)>>, -<<nng_aio.5#,nng_aio(5)>>, -<<nng_tls.5#,nng_tls(5)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tls_listener.5#,nng_tls_listener(5)>>, -<<nng_tls_options.5#,nng_tls_options(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_listener_accept.3tls#,nng_tls_listener_accept(3tls)>>, -<<nng_tls_listener_close.3tls#,nng_tls_listener_close(3tls)>>, -<<nng_tls_listener_free.3tls#,nng_tls_listener_free(3tls)>>, -<<nng_tls_listener_getopt.3tls#,nng_tls_listener_getopt(3tls)>>, -<<nng_tls_listener_listen.3tls#,nng_tls_listener_listen(3tls)>>, -<<nng_tls_listener_setopt.3tls#,nng_tls_listener_setopt(3tls)>>, -<<nng_tls_listener.5#,nng_tls_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 <<nng_tls_listener_accept.3tls#,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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_listener_alloc.3tls#,nng_tls_listener_alloc(3tls)>>, -<<nng_tls_listener_close.3tls#,nng_tls_listener_close(3tls)>>, -<<nng_tls_listener.5#,nng_tls_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 <<nng_tls_listener.5#,TLS listener>> _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: - -* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>> -* <<nng_tls_options.5#NNG_OPT_TLS_CONFIG,`NNG_OPT_TLS_CONFIG`>> - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_listener_setopt.3tls#,nng_tls_listener_setopt(3tls)>>, -<<nng_tls_getopt.3tls#,nng_tls_getopt(3tls)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tcp_options.5#,nng_tcp_options(5)>>, -<<nng_tls.5#,nng_tls(5)>>, -<<nng_tls_listener.5#,nng_tls_listener(5)>>, -<<nng_tls_options.5#,nng_tls_options(5)>> - 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 -<<nng_options.5#,`NNG_OPT_LOCADDR`>> option with the -<<nng_tls_listener_getopt.3tls#,`nng_tls_listener_getopt()`>> 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_listener_accept.3tls#,nng_tls_listener_accept(3tls)>>, -<<nng_tls_listener_alloc.3tls#,nng_tls_listener_alloc(3tls)>>, -<<nng_tls_listener_close.3tls#,nng_tls_listener_close(3tls)>>, -<<nng_tls_listener_free.3tls#,nng_tls_listener_free(3tls)>>, -<<nng_tls_listener_getopt.3tls#,nng_tls_listener_getopt(3tls)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_sockaddr.5#,nng_sockaddr(5)>>, -<<nng_tls_listener.5#,nng_tls_listener(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 -<<nng_tls_listener.5#,TLS listener>> _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: - -* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>> -* <<nng_tls_options.5#NNG_OPT_TLS_AUTH_MODE,`NNG_OPT_TLS_AUTH_MODE`>> -* <<nng_tls_options.5#NNG_OPT_TLS_CA_FILE,`NNG_OPT_TLS_CA_FILE`>> -* <<nng_tls_options.5#NNG_OPT_TLS_CERT_KEY_FILE,`NNG_OPT_TLS_CERT_KEY_FILE`>> -* <<nng_tls_options.5#NNG_OPT_TLS_CONFIG,`NNG_OPT_TLS_CONFIG`>> -* <<nng_tls_options.5#NNG_OPT_TLS_SERVER_NAME,`NNG_OPT_TLS_SERVER_NAME`>> - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_listener_getopt.3tls#,nng_tls_listener_getopt(3tls)>>, -<<nng_tls_setopt.3tls#,nng_tls_setopt(3tls)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tls.5#,nng_tls(5)>>, -<<nng_tls_listener.5#,nng_tls_listener(5)>>, -<<nng_tls_options.5#,nng_tls_options(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 <<nng_aio_set_iov.3#,`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 -<<nng_aio_result.3#,`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 -<<nng_aio_count.3#,`nng_aio_count()`>>. - -== 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] -<<nng_aio_alloc.3#,nng_aio_alloc(3)>>, -<<nng_aio_count.3#,nng_aio_count(3)>>, -<<nng_aio_result.3#,nng_aio_result(3)>>, -<<nng_aio_set_iov.3#,nng_aio_set_iov(3)>>, -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_close.3tls#,nng_tls_close(3tls)>>, -<<nng_tls_send.3tls#,nng_tls_send(3tls)>>, -<<nng_tls.5#,nng_tls(5)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 <<nng_aio_set_iov.3#,`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 <<nng_aio_result.3#,`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 -<<nng_aio_count.3#,`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_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] -<<nng_aio_alloc.3#,nng_aio_alloc(3)>>, -<<nng_aio_count.3#,nng_aio_count(3)>>, -<<nng_aio_result.3#,nng_aio_result(3)>>, -<<nng_aio_set_iov.3#,nng_aio_set_iov(3)>>, -<<nng_tls_close.3tls#,nng_tls_close(3tls)>>, -<<nng_tls_recv.3tls#,nng_tls_recv(3tls)>>, -<<nng_tls.5#,nng_tls(5)>>, -<<nng_strerror.3#,nng_strerror(3)>> 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. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// Copyright 2019 Devolutions <info@devolutions.net> -// -// 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 <nng/nng.h> -#include <nng/supplemental/tls/tls.h> - -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 -<<nng_tls.5#,TLS connection>> _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: - -* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>> -* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>> - -== 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] -<<nng_strerror.3#,nng_strerror(3)>>, -<<nng_tls_getopt.3tls#,nng_tls_getopt(3tls)>>, -<<nng_options.5#,nng_options(5)>>, -<<nng_tcp_options.5#,nng_tcp_options(5)>>, -<<nng_tls.5#,nng_tls(5)>>, -<<nng_tls_options.5#,nng_tls_options(5)>> |
