From f73cd76f54b8aead38689e0ea805d5d805dfbe96 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 30 Mar 2024 23:07:20 -0700 Subject: Staging work. converted nng_ipc. --- docs/man/nng_dialer_getopt.3.adoc | 149 -------------------- docs/man/nng_dialer_setopt.3.adoc | 134 ------------------ docs/man/nng_getopt.3.adoc | 145 ------------------- docs/man/nng_inproc_register.3.adoc | 47 ------- docs/man/nng_ipc.7.adoc | 126 ----------------- docs/man/nng_ipc_register.3.adoc | 47 ------- docs/man/nng_listener_getopt.3.adoc | 150 -------------------- docs/man/nng_listener_setopt.3.adoc | 136 ------------------ docs/man/nng_pipe_getopt.3.adoc | 155 --------------------- docs/man/nng_setopt.3.adoc | 127 ----------------- docs/man/nng_stream_close.3str.adoc | 65 --------- docs/man/nng_stream_dialer.5.adoc | 46 ------ docs/man/nng_stream_dialer_alloc.3str.adoc | 68 --------- docs/man/nng_stream_dialer_close.3str.adoc | 60 -------- docs/man/nng_stream_dialer_dial.3str.adoc | 65 --------- docs/man/nng_stream_dialer_free.3str.adoc | 54 ------- docs/man/nng_stream_dialer_get.3str.adoc | 143 ------------------- docs/man/nng_stream_dialer_set.3str.adoc | 133 ------------------ docs/man/nng_stream_free.3str.adoc | 61 -------- docs/man/nng_stream_get.3str.adoc | 146 ------------------- docs/man/nng_stream_listener.5.adoc | 48 ------- docs/man/nng_stream_listener_accept.3str.adoc | 64 --------- docs/man/nng_stream_listener_alloc.3str.adoc | 70 ---------- docs/man/nng_stream_listener_close.3str.adoc | 60 -------- docs/man/nng_stream_listener_free.3str.adoc | 54 ------- docs/man/nng_stream_listener_get.3str.adoc | 144 ------------------- docs/man/nng_stream_listener_listen.3str.adoc | 66 --------- docs/man/nng_stream_listener_set.3str.adoc | 133 ------------------ docs/man/nng_stream_recv.3str.adoc | 74 ---------- docs/man/nng_stream_send.3str.adoc | 74 ---------- docs/man/nng_stream_set.3str.adoc | 133 ------------------ docs/man/nng_tcp_register.3.adoc | 47 ------- docs/man/nng_tls_register.3.adoc | 44 ------ docs/man/nng_ws_register.3.adoc | 47 ------- docs/man/nng_wss_register.3.adoc | 47 ------- docs/man/nng_zt_register.3.adoc | 47 ------- docs/reference/book.toml | 16 +++ docs/reference/src/SUMMARY.md | 1 + docs/reference/src/old/nng_dialer_getopt.3.adoc | 149 ++++++++++++++++++++ docs/reference/src/old/nng_dialer_setopt.3.adoc | 134 ++++++++++++++++++ docs/reference/src/old/nng_getopt.3.adoc | 145 +++++++++++++++++++ docs/reference/src/old/nng_inproc_register.3.adoc | 47 +++++++ docs/reference/src/old/nng_ipc_register.3.adoc | 47 +++++++ docs/reference/src/old/nng_listener_getopt.3.adoc | 150 ++++++++++++++++++++ docs/reference/src/old/nng_listener_setopt.3.adoc | 136 ++++++++++++++++++ docs/reference/src/old/nng_pipe_getopt.3.adoc | 155 +++++++++++++++++++++ docs/reference/src/old/nng_setopt.3.adoc | 127 +++++++++++++++++ docs/reference/src/old/nng_tcp_register.3.adoc | 47 +++++++ docs/reference/src/old/nng_tls_register.3.adoc | 44 ++++++ docs/reference/src/old/nng_ws_register.3.adoc | 47 +++++++ docs/reference/src/old/nng_wss_register.3.adoc | 47 +++++++ docs/reference/src/old/nng_zt_register.3.adoc | 47 +++++++ docs/reference/src/refs.md | 14 +- .../src/stream/nng_stream_close.3str.adoc | 65 +++++++++ docs/reference/src/stream/nng_stream_dialer.5.adoc | 46 ++++++ .../src/stream/nng_stream_dialer_alloc.3str.adoc | 68 +++++++++ .../src/stream/nng_stream_dialer_close.3str.adoc | 60 ++++++++ .../src/stream/nng_stream_dialer_dial.3str.adoc | 65 +++++++++ .../src/stream/nng_stream_dialer_free.3str.adoc | 54 +++++++ .../src/stream/nng_stream_dialer_get.3str.adoc | 143 +++++++++++++++++++ .../src/stream/nng_stream_dialer_set.3str.adoc | 133 ++++++++++++++++++ .../reference/src/stream/nng_stream_free.3str.adoc | 61 ++++++++ docs/reference/src/stream/nng_stream_get.3str.adoc | 146 +++++++++++++++++++ .../src/stream/nng_stream_listener.5.adoc | 48 +++++++ .../stream/nng_stream_listener_accept.3str.adoc | 64 +++++++++ .../src/stream/nng_stream_listener_alloc.3str.adoc | 70 ++++++++++ .../src/stream/nng_stream_listener_close.3str.adoc | 60 ++++++++ .../src/stream/nng_stream_listener_free.3str.adoc | 54 +++++++ .../src/stream/nng_stream_listener_get.3str.adoc | 144 +++++++++++++++++++ .../stream/nng_stream_listener_listen.3str.adoc | 66 +++++++++ .../src/stream/nng_stream_listener_set.3str.adoc | 133 ++++++++++++++++++ .../reference/src/stream/nng_stream_recv.3str.adoc | 74 ++++++++++ .../reference/src/stream/nng_stream_send.3str.adoc | 74 ++++++++++ docs/reference/src/stream/nng_stream_set.3str.adoc | 133 ++++++++++++++++++ docs/reference/src/tran/ipc.md | 95 +++++++++++++ 75 files changed, 3206 insertions(+), 3212 deletions(-) delete mode 100644 docs/man/nng_dialer_getopt.3.adoc delete mode 100644 docs/man/nng_dialer_setopt.3.adoc delete mode 100644 docs/man/nng_getopt.3.adoc delete mode 100644 docs/man/nng_inproc_register.3.adoc delete mode 100644 docs/man/nng_ipc.7.adoc delete mode 100644 docs/man/nng_ipc_register.3.adoc delete mode 100644 docs/man/nng_listener_getopt.3.adoc delete mode 100644 docs/man/nng_listener_setopt.3.adoc delete mode 100644 docs/man/nng_pipe_getopt.3.adoc delete mode 100644 docs/man/nng_setopt.3.adoc delete mode 100644 docs/man/nng_stream_close.3str.adoc delete mode 100644 docs/man/nng_stream_dialer.5.adoc delete mode 100644 docs/man/nng_stream_dialer_alloc.3str.adoc delete mode 100644 docs/man/nng_stream_dialer_close.3str.adoc delete mode 100644 docs/man/nng_stream_dialer_dial.3str.adoc delete mode 100644 docs/man/nng_stream_dialer_free.3str.adoc delete mode 100644 docs/man/nng_stream_dialer_get.3str.adoc delete mode 100644 docs/man/nng_stream_dialer_set.3str.adoc delete mode 100644 docs/man/nng_stream_free.3str.adoc delete mode 100644 docs/man/nng_stream_get.3str.adoc delete mode 100644 docs/man/nng_stream_listener.5.adoc delete mode 100644 docs/man/nng_stream_listener_accept.3str.adoc delete mode 100644 docs/man/nng_stream_listener_alloc.3str.adoc delete mode 100644 docs/man/nng_stream_listener_close.3str.adoc delete mode 100644 docs/man/nng_stream_listener_free.3str.adoc delete mode 100644 docs/man/nng_stream_listener_get.3str.adoc delete mode 100644 docs/man/nng_stream_listener_listen.3str.adoc delete mode 100644 docs/man/nng_stream_listener_set.3str.adoc delete mode 100644 docs/man/nng_stream_recv.3str.adoc delete mode 100644 docs/man/nng_stream_send.3str.adoc delete mode 100644 docs/man/nng_stream_set.3str.adoc delete mode 100644 docs/man/nng_tcp_register.3.adoc delete mode 100644 docs/man/nng_tls_register.3.adoc delete mode 100644 docs/man/nng_ws_register.3.adoc delete mode 100644 docs/man/nng_wss_register.3.adoc delete mode 100644 docs/man/nng_zt_register.3.adoc create mode 100644 docs/reference/src/old/nng_dialer_getopt.3.adoc create mode 100644 docs/reference/src/old/nng_dialer_setopt.3.adoc create mode 100644 docs/reference/src/old/nng_getopt.3.adoc create mode 100644 docs/reference/src/old/nng_inproc_register.3.adoc create mode 100644 docs/reference/src/old/nng_ipc_register.3.adoc create mode 100644 docs/reference/src/old/nng_listener_getopt.3.adoc create mode 100644 docs/reference/src/old/nng_listener_setopt.3.adoc create mode 100644 docs/reference/src/old/nng_pipe_getopt.3.adoc create mode 100644 docs/reference/src/old/nng_setopt.3.adoc create mode 100644 docs/reference/src/old/nng_tcp_register.3.adoc create mode 100644 docs/reference/src/old/nng_tls_register.3.adoc create mode 100644 docs/reference/src/old/nng_ws_register.3.adoc create mode 100644 docs/reference/src/old/nng_wss_register.3.adoc create mode 100644 docs/reference/src/old/nng_zt_register.3.adoc create mode 100644 docs/reference/src/stream/nng_stream_close.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_dialer.5.adoc create mode 100644 docs/reference/src/stream/nng_stream_dialer_alloc.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_dialer_close.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_dialer_dial.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_dialer_free.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_dialer_get.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_dialer_set.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_free.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_get.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_listener.5.adoc create mode 100644 docs/reference/src/stream/nng_stream_listener_accept.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_listener_alloc.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_listener_close.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_listener_free.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_listener_get.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_listener_listen.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_listener_set.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_recv.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_send.3str.adoc create mode 100644 docs/reference/src/stream/nng_stream_set.3str.adoc create mode 100644 docs/reference/src/tran/ipc.md diff --git a/docs/man/nng_dialer_getopt.3.adoc b/docs/man/nng_dialer_getopt.3.adoc deleted file mode 100644 index a4083819..00000000 --- a/docs/man/nng_dialer_getopt.3.adoc +++ /dev/null @@ -1,149 +0,0 @@ -= nng_dialer_getopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_dialer_getopt - get dialer option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_dialer_getopt(nng_dialer d, const char *opt, void *val, size_t *valszp); - -int nng_dialer_getopt_bool(nng_dialer d, const char *opt, bool *bvalp); - -int nng_dialer_getopt_int(nng_dialer d, const char *opt, int *ivalp); - -int nng_dialer_getopt_ms(nng_dialer d, const char *opt, nng_duration *durp); - -int nng_dialer_getopt_ptr(nng_dialer d, const char *opt, void **ptr); - -int nng_dialer_getopt_size(nng_dialer d, const char *opt, size_t *zp); - -int nng_dialer_getopt_sockaddr(nng_dialer d, const char *opt, nng_sockaddr *sap); - -int nng_dialer_getopt_string(nng_dialer d, const char *opt, char **strp); - -int nng_dialer_getopt_uint64(nng_dialer d, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_dialer_get.3.adoc[nng_dialer_get]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, dialer))) -The `nng_dialer_getopt()` functions are used to retrieve option values for -the xref:nng_dialer.5.adoc[dialer] _d_. -The actual options that may be retrieved in this way -vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. - -Additionally some transport-specific options are documented with the transports themselves. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the 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_dialer_getopt()`:: -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_. + - + -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 validate that the returned size in _valszp_ does not -exceed the original buffer size to check for truncation. + - + -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_dialer_getopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _bvalp_. - -`nng_dialer_getopt_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_dialer_getopt_ms()`:: -This function is used to retrieve time xref:nng_duration.5.adoc[durations] -(such as timeouts), stored in _durp_ as a number of milliseconds. -(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and -the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) - -`nng_dialer_getopt_ptr()`:: -This function is used to retrieve a pointer, _ptr_, to structured data. -The data referenced by _ptr_ 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. - -`nng_dialer_getopt_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_dialer_getopt_sockaddr()`:: -This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] -into the value referenced by _sap_. - -`nng_dialer_getopt_string()`:: -This function is used to retrieve a string into _strp_. -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_dialer_getopt_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options related to identifiers, network -numbers, and similar. - -== RETURN VALUES - -These functions returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] -xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)] -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_dialer.5.adoc[nng_dialer(5)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_dialer_setopt.3.adoc b/docs/man/nng_dialer_setopt.3.adoc deleted file mode 100644 index 3aaff1eb..00000000 --- a/docs/man/nng_dialer_setopt.3.adoc +++ /dev/null @@ -1,134 +0,0 @@ -= nng_dialer_setopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_dialer_setopt - set dialer option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_dialer_setopt(nng_dialer d, const char *opt, const void *val, - size_t valsz); - -int nng_dialer_setopt_bool(nng_dialer d, const char *opt, bool bval); - -int nng_dialer_setopt_int(nng_dialer d, const char *opt, int ival); - -int nng_dialer_setopt_ms(nng_dialer d, const char *opt, nng_duration dur); - -int nng_dialer_setopt_ptr(nng_dialer d, const char *opt, void *ptr); - -int nng_dialer_setopt_size(nng_dialer d, const char *opt, size_t z); - -int nng_dialer_setopt_string(nng_dialer d, const char *opt, const char *str); - -int nng_dialer_setopt_uint64(nng_dialer d, const char *opt, uint64_t u64); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_dialer_set.3.adoc[nng_dialer_set]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, dialer))) -The `nng_dialer_setopt()` functions are used to configure options for -the xref:nng_dialer.5.adoc[dialer] _d_. -The actual options that may be configured in this way -vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. - -Additionally some transport-specific options are documented with the -transports themselves. - -NOTE: Once a dialer has started, it is generally not possible to change -its configuration. - -=== Forms - -In all of these forms, the option _opt_ is configured on the dialer _d_. - -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_dialer_setopt()`:: -This function is untyped, and can be used to configure any arbitrary data. -The _val_ pointer addresses the data to copy, and _valsz_ 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_dialer_setopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The _bval_ is passed to the option. - -`nng_dialer_setopt_int()`:: -This function is for options which take an integer (`int`). -The _ival_ is passed to the option. - -`nng_dialer_setopt_ms()`:: -This function is used to configure time durations (such as timeouts) using -type xref:nng_duration.5.adoc[`nng_duration`]. -The duration _dur_ is an integer number of milliseconds. - -`nng_dialer_setopt_ptr()`:: -This function is used to pass a pointer, _ptr_, to structured data. -The data referenced by _ptr_ is generally managed by other functions. -For example, TLS configuration objects created with -(xref:nng_tls_config_alloc.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. - -`nng_dialer_setopt_size()`:: -This function is used to configure a size, _z_, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_dialer_setopt_string()`:: -This function is used to pass configure a string, _str_. -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_dialer_setopt_uint64()`:: -This function is used to configure a 64-bit unsigned value, _u64_. -This is typically used for options related to identifiers, network numbers, -and such. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. -`NNG_EINVAL`:: The value being passed is invalid. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EREADONLY`:: The option _opt_ is read-only. -`NNG_ESTATE`:: The dialer _d_ is already started. - -== SEE ALSO - -[.text-left] -xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] -xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_dialer.5.adoc[nng_dialer(5)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_getopt.3.adoc b/docs/man/nng_getopt.3.adoc deleted file mode 100644 index 364d8f71..00000000 --- a/docs/man/nng_getopt.3.adoc +++ /dev/null @@ -1,145 +0,0 @@ -= nng_getopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_getopt - get socket option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_getopt(nng_socket s, const char *opt, void *val, size_t *valszp); - -int nng_getopt_bool(nng_socket s, const char *opt, bool *bvalp); - -int nng_getopt_int(nng_socket s, const char *opt, int *ivalp); - -int nng_getopt_ms(nng_socket s, const char *opt, nng_duration *durp); - -int nng_getopt_ptr(nng_socket s, const char *opt, void **ptr); - -int nng_getopt_size(nng_socket s, const char *opt, size_t *zp); - -int nng_getopt_string(nng_socket s, const char *opt, char **strp); - -int nng_getopt_uint64(nng_socket s, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_socket_get.3.adoc[nng_socket_get]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, socket))) -The `nng_getopt()` functions are used to retrieve option values for -the xref:nng_socket.5.adoc[socket] _s_. -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)]. - -Additionally transport-specific options and protocol-specific options are -documented with the transports and protocols themselves. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the socket _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_getopt()`:: -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_. -+ -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. -+ -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 _bvalp_. - -`nng_getopt_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_getopt_ms()`:: -This function is used to retrieve time xref:nng_duration.5.adoc[durations] -(such as timeouts), stored in _durp_ as a number of milliseconds. -(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and -the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) - -`nng_getopt_ptr()`:: -This function is used to retrieve a pointer, _ptr_, to structured data. -The data referenced by _ptr_ 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. - -`nng_getopt_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_getopt_string()`:: -This function is used to retrieve a string into _strp_. -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_getopt_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options related to identifiers, network -numbers, and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)], -xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)], -xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], -xref:nng_setopt.3.adoc[nng_setopt(3)], -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_inproc_register.3.adoc b/docs/man/nng_inproc_register.3.adoc deleted file mode 100644 index 8379a4e8..00000000 --- a/docs/man/nng_inproc_register.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_inproc_register(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_inproc_register - register inproc transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_inproc_register(void); ----- - -== DESCRIPTION - -The `nng_inproc_register()` function registers the -((_inproc_ transport))(((transport, _inproc_))) for use. - -NOTE: This function is deprecated, and may be removed from a future release. -It is no longer necessary to explicitly register transports. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_inproc.7.adoc[nng_inproc(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ipc.7.adoc b/docs/man/nng_ipc.7.adoc deleted file mode 100644 index c085e4d2..00000000 --- a/docs/man/nng_ipc.7.adoc +++ /dev/null @@ -1,126 +0,0 @@ -= nng_ipc(7) -// -// Copyright 2023 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc - IPC transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_ipc_register(void); ----- - -== DESCRIPTION - -(((IPC)))(((transport, _ipc_))) -The ((_ipc_ transport)) provides communication support between -sockets within different processes on the same host. -For POSIX platforms, this is implemented using ((UNIX domain sockets)). -For Windows, this is implemented using Windows ((Named Pipes)). -Other platforms may have different implementation strategies. - -// We need to insert a reference to the nanomsg RFC. - -=== Registration - -This transport is generally built-in to the core, so -no extra steps to use it should be necessary. - -=== URI Formats - -==== Traditional Names - -(((URI, `ipc://`))) -This transport uses URIs using the scheme `ipc://`, followed by a path -name in the file system where the socket or named pipe should be created. - -TIP: On Windows, all names are prefixed by `\\.\pipe\` and do not -reside in the normal file system. -On POSIX platforms, the path is taken literally, and is relative to -the current directory, unless it begins with `/`, in which case it is -relative to the root directory. - -NOTE: When using relative paths on POSIX systems, the address used and returned -in properties like `NNG_OPT_LOCADDR` and `NNG_OPT_URL` will also be relative. -Consequently, they will only be interpreted the same by processes that have -the same working directory. -To ensure maximum portability and safety, absolute paths are recommended -whenever possible. - -NOTE: If compatibility with legacy _nanomsg_ applications is required, -then path names must not be longer than 122 bytes, including the final -`NUL` byte. -This is because legacy versions of _nanomsg_ cannot express URLs -longer than 128 bytes, including the `ipc://` prefix. - -==== UNIX Aliases - -(((URI, `unix://`))) -The `unix://` scheme is an alias for `ipc://` and can be used inter-changeably, but only -on POSIX systems. - -The purpose of this scheme is to support a future transport making use of `AF_UNIX` -on Windows systems, at which time it will be necessary to discriminate between -the Named Pipes and the `AF_UNIX` based transports. - -==== Abstract Names - -(((URI, `abstract://`))) -On Linux, this transport also can support abstract sockets. -Abstract sockets use a URI-encoded name after the scheme, which allows arbitrary values to be conveyed -in the path, including embedded `NUL` bytes. -For example, the name `"a\0b"` would be represented as `abstract://a%00b`. - -TIP: An empty name may be used with a listener to request "`auto bind`" be used to select a name. -In this case the system will allocate a free name. -The name assigned may be retrieved using `NNG_OPT_LOCADDR`. - -NOTE: _NNG_ cannot represent an abstract socket with the empty name. - -NOTE: Abstract names do not include the leading `NUL` byte used in the low-level socket address. - -Abstract sockets do not have any representation in the file system, and are automatically freed by -the system when no longer in use. -Abstract sockets ignore socket permissions, but it is still possible to determine the credentials -of the peer with `NNG_OPT_PEER_UID`, etc. - -=== Socket Address - -When using an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] structure, -the actual structure is of type xref:nng_sockaddr_ipc.5.adoc[`nng_sockaddr_ipc`], -except for abstract sockets, which use xref:nng_sockaddr_abstract.5.adoc[`nng_sockaddr_abstract`]. - -=== Transport Options - -The following transport options are supported by this transport, -where supported by the underlying platform. - -* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_PERMISSIONS[`NNG_OPT_IPC_PERMISSIONS`] -* xref:nng_ipc_options.5.adoc#NNG_OPT_IPC_SECURITY_DESCRIPTOR[`NNG_OPT_IPC_SECURITY_DESCRIPTOR`] -* xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`] -* xref:nng_options.5.adoc#NNG_OPT_REMADDR[`NNG_OPT_REMADDR`] -* xref:nng_options.5.adoc#NNG_OPT_PEER_GID[`NNG_OPT_PEER_GID`] -* xref:nng_options.5.adoc#NNG_OPT_PEER_PID[`NNG_OPT_PEER_PID`] -* xref:nng_options.5.adoc#NNG_OPT_PEER_UID[`NNG_OPT_PEER_UID`] -* xref:nng_options.5.adoc#NNG_OPT_PEER_ZONEID[`NNG_OPT_PEER_ZONEID`] -* xref:nng_options.5.adoc#NNG_OPT_URL[`NNG_OPT_URL`] - -== SEE ALSO - -[.text-left] -xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], -xref:nng_ipc_options.5.adoc[nng_ipc_options(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ipc_register.3.adoc b/docs/man/nng_ipc_register.3.adoc deleted file mode 100644 index 64da4b00..00000000 --- a/docs/man/nng_ipc_register.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_ipc_register(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_register - register ipc transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_ipc_register(void); ----- - -== DESCRIPTION - -The `nng_ipc_register()` function registers the -((_ipc_ transport))(((transport, _ipc_))) for use. - -NOTE: This function is deprecated, and may be removed from a future release. -It is no longer necessary to explicitly register transports. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_ipc.7.adoc[nng_ipc(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_listener_getopt.3.adoc b/docs/man/nng_listener_getopt.3.adoc deleted file mode 100644 index 828f440d..00000000 --- a/docs/man/nng_listener_getopt.3.adoc +++ /dev/null @@ -1,150 +0,0 @@ -= nng_listener_getopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_listener_getopt - get listener option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_listener_getopt(nng_listener l, const char *opt, void *val, size_t *valszp); - -int nng_listener_getopt_bool(nng_listener l, const char *opt, bool *bvalp); - -int nng_listener_getopt_int(nng_listener l, const char *opt, int *ivalp); - -int nng_listener_getopt_ms(nng_listener l, const char *opt, nng_duration *durp); - -int nng_listener_getopt_ptr(nng_listener l, const char *opt, void **ptr); - -int nng_listener_getopt_size(nng_listener l, const char *opt, size_t *zp); - -int nng_listener_getopt_sockaddr(nng_listener l, const char *opt, nng_sockaddr *sap); - -int nng_listener_getopt_string(nng_listener l, const char *opt, char **strp); - -int nng_listener_getopt_uint64(nng_listener l, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_listener_get.3.adoc[nng_listener_get]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, listener))) -The `nng_listener_getopt()` functions are used to retrieve option values for -the xref:nng_listener.5.adoc[listener] _l_. -The actual options that may be retrieved in this way -vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. - -Additionally some transport-specific options -are documented with the transports themselves. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the 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_listener_getopt()`:: -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_. + - + -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 validate that the returned size in _valszp_ does not -exceed the original buffer size to check for truncation. + - + -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_listener_getopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _bvalp_. - -`nng_listener_getopt_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_listener_getopt_ms()`:: -This function is used to retrieve time xref:nng_duration.5.adoc[durations] -(such as timeouts), stored in _durp_ as a number of milliseconds. - -`nng_listener_getopt_ptr()`:: -This function is used to retrieve a pointer, _ptr_, to structured data. -The data referenced by _ptr_ 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. - -`nng_listener_getopt_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_listener_getopt_sockaddr()`:: -This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] -into the value referenced by _sap_. - -`nng_listener_getopt_string()`:: -This function is used to retrieve a string into _strp_. -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_listener_getopt_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options related to identifiers, network -numbers, and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_listen.3.adoc[nng_listen(3)], -xref:nng_listener_create.3.adoc[nng_listener_create(3)] -xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)] -xref:nng_getopt.3.adoc[nng_getopt(3)], -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_listener.5.adoc[nng_listener(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_listener_setopt.3.adoc b/docs/man/nng_listener_setopt.3.adoc deleted file mode 100644 index 25411adc..00000000 --- a/docs/man/nng_listener_setopt.3.adoc +++ /dev/null @@ -1,136 +0,0 @@ -= nng_listener_setopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_listener_setopt - set listener option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_listener_setopt(nng_listener l, const char *opt, const void *val, - size_t valsz); - -int nng_listener_setopt_bool(nng_listener l, const char *opt, bool bval); - -int nng_listener_setopt_int(nng_listener l, const char *opt, int ival); - -int nng_listener_setopt_ms(nng_listener l, const char *opt, nng_duration dur); - -int nng_listener_setopt_ptr(nng_listener l, const char *opt, void *ptr); - -int nng_listener_setopt_size(nng_listener l, const char *opt, size_t z); - -int nng_listener_setopt_string(nng_listener l, const char *opt, const char *str); - -int nng_listener_setopt_uint64(nng_listener l, const char *opt, uint64_t u64); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_listener_set.3.adoc[nng_listener_set]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, listener))) -The `nng_listener_setopt()` functions are used to configure options for -the xref:nng_listener.5.adoc[listener] _l_. -The actual options that may be configured in this way -vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. - -Additionally some transport-specific options -are documented with the transports themselves. - -NOTE: Once a listener has started, it is generally not possible to change -its configuration. - -=== Forms - -In all of these forms, the option _opt_ is configured on the listener _l_. - -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. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_listener_setopt()`:: -This function is untyped, and can be used to configure any arbitrary data. -The _val_ pointer addresses the data to copy, and _valsz_ is the -size of the objected located at _val_. - -`nng_listener_setopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The _bval_ is passed to the option. - -`nng_listener_setopt_int()`:: -This function is for options which take an integer (`int`). -The _ival_ is passed to the option. - -`nng_listener_setopt_ms()`:: -This function is used to configure time durations (such as timeouts) using -type xref:nng_duration.5.adoc[`nng_duration`]. -The duration _dur_ is an integer number of milliseconds. - -`nng_listener_setopt_ptr()`:: -This function is used to pass a pointer, _ptr_, to structured data. -The data referenced by _ptr_ is generally managed by other functions. -For example, TLS configuration objects created with -(xref:nng_tls_config_alloc.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. - -`nng_listener_setopt_size()`:: -This function is used to configure a size, _z_, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_listener_setopt_string()`:: -This function is used to pass configure a string, _str_. -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_listener_setopt_uint64()`:: -This function is used to configure a 64-bit unsigned value, _u64_. -This is typically used for options related to identifiers, network numbers, -and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. -`NNG_EINVAL`:: The value being passed is invalid. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EREADONLY`:: The option _opt_ is read-only. -`NNG_ESTATE`:: The listener _l_ is already started. - -== SEE ALSO - -[.text-left] -xref:nng_listen.3.adoc[nng_listen(3)], -xref:nng_listener_create.3.adoc[nng_listener_create(3)] -xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)] -xref:nng_setopt.3.adoc[nng_setopt(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_listener.5.adoc[nng_listener(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pipe_getopt.3.adoc b/docs/man/nng_pipe_getopt.3.adoc deleted file mode 100644 index 648abbcc..00000000 --- a/docs/man/nng_pipe_getopt.3.adoc +++ /dev/null @@ -1,155 +0,0 @@ -= nng_pipe_getopt(3) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_pipe_getopt - get pipe option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_pipe_getopt(nng_pipe p, const char *opt, void *val, size_t *valszp); - -int nng_pipe_getopt_bool(nng_pipe p, const char *opt, bool *bvalp); - -int nng_pipe_getopt_int(nng_pipe p, const char *opt, int *ivalp); - -int nng_pipe_getopt_ms(nng_pipe p, const char *opt, nng_duration *durp); - -int nng_pipe_getopt_ptr(nng_pipe p, const char *opt, void **ptr); - -int nng_pipe_getopt_sockaddr(nng_pipe p, const char *opt, nng_sockaddr *sap); - -int nng_pipe_getopt_string(nng_pipe p, const char *opt, char **strp); - -int nng_pipe_getopt_size(nng_pipe p, const char *opt, size_t *zp); - -int nng_pipe_getopt_uint64(nng_pipe p, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -NOTE: These functions are deprecated. Please see xref:nng_pipe_get.3.adoc[nng_pipe_get]. - -(((options, pipe))) -The `nng_pipe_getopt()` functions are used to retrieve option values for -the xref:nng_pipe.5.adoc[pipe] _p_. -The actual options that may be retrieved in this way -vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. -Additionally some transport-specific options and protocol-specific options are -documented with the transports and protocols themselves. - -NOTE: All options on a pipe are read-only values. -Modification of options may be done before the pipe is created using -xref:nng_listener_setopt.3.adoc[`nng_listener_setopt()`] or -xref:nng_dialer_getopt.3.adoc[`nng_dialer_setopt()`]. - -Any option that is set on a dialer or listener will normally be retrievable -from pipes created by that dialer or listener. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the pipe _p_. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_pipe_getopt()`:: -This is untyped, and can be used to retrieve the value of any option. -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_. + - + -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 -size returned 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_pipe_getopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _bvalp_. - -`nng_pipe_getopt_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_pipe_getopt_ms()`:: -This function is used to retrieve time durations -(xref:nng_duration.5.adoc[`nng_duration`]) in milliseconds, which are stored in -_durp_. - -`nng_pipe_getopt_ptr()`:: -This function is used to retrieve a pointer, _ptr_, to structured data. -The data referenced by _ptr_ 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. - -`nng_pipe_getopt_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_pipe_getopt_sockaddr()`:: -This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] -into _sap_. - -`nng_pipe_getopt_string()`:: -This function is used to retrieve a string into _strp_. -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_pipe_getopt_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options -related to identifiers, network numbers, and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _p_ does not refer to an open pipe. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)] -xref:nng_getopt.3.adoc[nng_getopt(3)], -xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)] -xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe(3)] -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_pipe.5.adoc[nng_pipe(5)], -xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_setopt.3.adoc b/docs/man/nng_setopt.3.adoc deleted file mode 100644 index 6c21cf95..00000000 --- a/docs/man/nng_setopt.3.adoc +++ /dev/null @@ -1,127 +0,0 @@ -= nng_setopt(3) - -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. - -== NAME - -nng_setopt - set socket option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_setopt(nng_socket s, const char *opt, const void *val, size_t valsz); - -int nng_setopt_bool(nng_socket s, const char *opt, bool bval); - -int nng_setopt_int(nng_socket s, const char *opt, int ival); - -int nng_setopt_ms(nng_socket s, const char *opt, nng_duration dur); - -int nng_setopt_ptr(nng_socket s, const char *opt, void *ptr); - -int nng_setopt_size(nng_socket s, const char *opt, size_t z); - -int nng_setopt_string(nng_socket s, const char *opt, const char *str); - -int nng_setopt_uint64(nng_socket s, const char *opt, uint64_t u64); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_socket_set.3.adoc[nng_socket_set]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, socket))) -The `nng_setopt()` functions are used to configure options for -the socket _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_setopt()`:: -This function is untyped, and can be used to configure any arbitrary data. -The _val_ pointer addresses the data to copy, and _valsz_ 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_setopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The _bval_ is passed to the option. - -`nng_setopt_int()`:: -This function is for options which take an integer (`int`). -The _ival_ is passed to the option. - -`nng_setopt_ms()`:: -This function is used to configure time durations (such as timeouts) using -type xref:nng_duration.5.adoc[`nng_duration`]. -The duration _dur_ is an integer number of milliseconds. - -`nng_setopt_ptr()`:: -This function is used to pass a pointer, _ptr_, to structured data. -The data referenced by _ptr_ is generally managed by other functions. -For example, TLS configuration objects created with -(xref:nng_tls_config_alloc.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. - -`nng_setopt_size()`:: -This function is used to configure a size, _z_, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_setopt_string()`:: -This function is used to pass configure a string, _str_. -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_setopt_uint64()`:: -This function is used to configure a 64-bit unsigned value, _u64_. -This is typically used for options related to identifiers, network numbers, -and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. -`NNG_EINVAL`:: The value being passed is invalid. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EREADONLY`:: The option _opt_ is read-only. -`NNG_ESTATE`:: The socket is in an inappropriate state for setting this option. - -== SEE ALSO - -[.text-left] -xref:nng_getopt.3.adoc[nng_getopt(3)], -xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)], -xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stream_close.3str.adoc b/docs/man/nng_stream_close.3str.adoc deleted file mode 100644 index 9e7b8d6a..00000000 --- a/docs/man/nng_stream_close.3str.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= nng_stream_close(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_close - close byte stream - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_stream_close(nng_stream *s); ----- - -== DESCRIPTION - -The `nng_stream_close()` function closes the -xref:nng_stream.5.adoc[byte stream] _s_. - -If any operations are pending, such as -xref:nng_stream_send.3str.adoc[`nng_stream_send()`] -or -xref:nng_stream_recv.3str.adoc[`nng_stream_recv()`], -they will be terminated with -an `NNG_ECLOSED` error condition. -Also, any new operations will fail with `NNG_ECLOSED` after the connection -is closed. - -NOTE: Closing the connection while data is in transmission will likely -lead to loss of that data. -There is no automatic linger or flush to ensure that the socket send buffers -have completely transmitted. - -NOTE: Closing the connection does not free the resources associated with it. -Once it is certain that no more operations are pending on the connection, -it should be freed with -xref:nng_stream_free.3str.adoc[`nng_stream_free()`]. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_free.3str.adoc[nng_stream_free(3str)], -xref:nng_stream_recv.3str.adoc[nng_stream_recv(3str)], -xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], -xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/man/nng_stream_dialer.5.adoc b/docs/man/nng_stream_dialer.5.adoc deleted file mode 100644 index eef23a3d..00000000 --- a/docs/man/nng_stream_dialer.5.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= nng_stream_dialer(5) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer - byte stream dialer - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stream_dialer nng_stream_dialer; ----- - -== DESCRIPTION - -(((byte stream, dialer))) -An `nng_stream_dialer` is a handle to a dialer for byte streams, -and is responsible for creating -xref:nng_stream.5.adoc[`nng_stream`] objects (corresponding to connected byte -streams) by connecting to remote peers. - -NOTE: The `nng_stream_dialer` object is used for low-level byte stream -connections, and should not be confused with a high-level -xref:nng_dialer.5.adoc[`nng_dialer`] object. - -== SEE ALSO - -[.text-left] -xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], -xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)], -xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], -xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)], -xref:nng_stream.5.adoc[nng_stream(5)], -xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_dialer_alloc.3str.adoc b/docs/man/nng_stream_dialer_alloc.3str.adoc deleted file mode 100644 index 0c2db67c..00000000 --- a/docs/man/nng_stream_dialer_alloc.3str.adoc +++ /dev/null @@ -1,68 +0,0 @@ -= nng_stream_dialer_alloc(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer_alloc - allocate byte stream dialer - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_stream_dialer_alloc(nng_stream_dialer **dp, const char *addr); - -int nng_stream_dialer_alloc_url(nng_stream_dialer **dp, const nng_url *url); ----- - -== DESCRIPTION - -These functions allocates a dialer for byte streams. -Dialers create -xref:nng_stream.5.adoc[`nng_stream`] objects by initiating outgoing -connections, via the -xref:nng_stream_dialer_dial.3str.adoc[`nng_stream_dialer_dial()`] function. - -The first form, `nng_stream_dialer_alloc()`, connects to the address -specified by _addr_, which should be a string representing a URL. - -The second form, `nng_stream_dialer_alloc_url()`, takes a pre-parsed -or pre-constructed -xref:nng_url.5.adoc[`nng_url`] object to determine the remote address. - -These functions may support different URL schemes, such as -`ipc://`, `tcp://`, `tls+tcp://`, or `ws://`. - -Both forms store the dialer in the location referenced by _dp_. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ENOTSUP`:: The URL scheme is not supported by the implementation. -`NNG_EADDRINVAL`:: The URL requested is invalid. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)] -xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)] -xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)] -xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get(3str)] -xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set(3str)] -xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/man/nng_stream_dialer_close.3str.adoc b/docs/man/nng_stream_dialer_close.3str.adoc deleted file mode 100644 index 59d9dec0..00000000 --- a/docs/man/nng_stream_dialer_close.3str.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_stream_dialer_close(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer_close - close byte stream dialer - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_stream_dialer_close(nng_stream_dialer *d); ----- - -== DESCRIPTION - -The `nng_stream_dialer_close()` function closes the supplied byte stream -dialer _d_, -but does not free the underlying resources associated with it. - -If any -xref:nng_stream_dialer_dial.3str.adoc[dial] -operations using _d_ are -in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -Furthermore any future accesses to the dialer _d_ will also result in -`NNG_ECLOSED`. - -NOTE: This function does not release the memory for the dialer, so the -application should still free the memory using -xref:nng_stream_dialer_free.3str.adoc[`nng_stream_dialer_free()`] -once it is certain that nothing else is using it. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], -xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], -xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)], -xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/man/nng_stream_dialer_dial.3str.adoc b/docs/man/nng_stream_dialer_dial.3str.adoc deleted file mode 100644 index 8dcd4ec2..00000000 --- a/docs/man/nng_stream_dialer_dial.3str.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= nng_stream_dialer_dial(3str) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer_dial - initiate outgoing byte stream connection - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_stream_dialer_dial(nng_stream_dialer *d, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_stream_dialer_dial()` attempts to establish a connection to the -remote peer for the dialer _d_. -The operation is completed asynchronously, using _aio_. - -TIP: The peer address is determined by the address specified using -xref:nng_stream_dialer_alloc.3str.adoc[`nng_stream_dialer_alloc()`] or -xref:nng_stream_dialer_alloc.3str.adoc[`nng_stream_dialer_alloc_url()`]. - -If a connection is successfully established, the _aio_ will have the -resulting -xref:nng_stream.5.adoc[`nng_stream`] object stored as its first output. -(See -xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`].) - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_EADDRINVAL`:: The address specified is invalid. -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECLOSED`:: The dialer is closed. -`NNG_ECONNREFUSED`:: The connection was refused by the server. -`NNG_ECONNRESET`:: The connection was reset by the server. -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], -xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)], -xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_stream.5.adoc[nng_stream(5)], -xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/man/nng_stream_dialer_free.3str.adoc b/docs/man/nng_stream_dialer_free.3str.adoc deleted file mode 100644 index 6669ca1e..00000000 --- a/docs/man/nng_stream_dialer_free.3str.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= nng_stream_dialer_free(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions - -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer_free - free byte stream dialer - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_stream_dialer_free(nng_stream_dialer *d); ----- - -== DESCRIPTION - -The `nng_stream_dialer_free()` function closes the supplied -byte stream dialer _d_, -and frees the underlying resources associated with it. - -If any -xref:nng_stream_dialer_dial.3str.adoc[dial] operations using _d_ are -in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -WARNING: It is important that the application ensure that no further accesses -are made to _d_, as the memory backing it will be reclaimed for other uses. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], -xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)], -xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], -xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/man/nng_stream_dialer_get.3str.adoc b/docs/man/nng_stream_dialer_get.3str.adoc deleted file mode 100644 index 4023e56f..00000000 --- a/docs/man/nng_stream_dialer_get.3str.adoc +++ /dev/null @@ -1,143 +0,0 @@ -= nng_stream_dialer_get(3str) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer_get - get option from byte stream dialer - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_stream_dialer_get(nng_stream_dialer *d, const char *opt, void *val, size_t *sizep); - -int nng_stream_dialer_get_bool(nng_stream_dialer *d, const char *opt, bool *valp); - -int nng_stream_dialer_get_int(nng_stream_dialer *d, const char *opt, int *valp); - -int nng_stream_dialer_get_ms(nng_stream_dialer *d, const char *opt, nng_duration *valp); - -int nng_stream_dialer_get_ptr(nng_stream_dialer *d, const char *opt, void **valp); - -int nng_stream_dialer_get_size(nng_stream_dialer *d, const char *opt, size_t *valp); - -int nng_stream_dialer_get_addr(nng_stream_dialer *d, const char *opt, nng_sockaddr *valp); - -int nng_stream_dialer_get_string(nng_stream_dialer *d, const char *opt, char **valp); - -int nng_stream_dialer_get_uint64(nng_stream_dialer *d, const char *opt, uint64_t *valp); ----- - -== DESCRIPTION - - -The `nng_stream_dialer_get()` functions are used to retrieve option values for the -xref:nng_stream_dialer.5.adoc[byte stream dialer] _d_. - -The actual options that may be retrieved in this way vary. -A number of them are documented in -xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the connected -byte stream dialer _d_. -The forms vary based on the type of the option they take. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_stream_dialer_get()`:: -This function is untyped and can be used to retrieve the value of any option. -The caller must store a pointer to a buffer to receive the value in _val_, -and the size of the buffer shall be stored at the location referenced by -_sizep_. -+ -When the function returns, the actual size of the data copied (or that -would have been copied if sufficient space were present) is stored at -the location referenced by _sizep_. -If the caller's buffer is not large enough to hold the entire object, -then the copy is truncated. -Therefore the caller should check for truncation by verifying that the -returned size in _sizep_ does not exceed the original buffer size. -+ -It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. -This can be used to determine the size of the buffer needed to receive -the object. -+ -TIP: It may be easier to use one of the typed forms of this function. - -`nng_stream_dialer_get_bool()`:: -This function is for options which take a Boolean (`bool`). - -`nng_stream_dialer_get_int()`:: -This function is for options which take an integer (`int`). - -`nng_stream_dialer_get_ms()`:: -This function is used to retrieve time -xref:nng_duration.5.adoc[durations] -(such as timeouts), stored as a number of milliseconds. -(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and -the special value ((`NNG_DURATION_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 underlying 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 deleted file mode 100644 index bd4ac478..00000000 --- a/docs/man/nng_stream_dialer_set.3str.adoc +++ /dev/null @@ -1,133 +0,0 @@ -= nng_stream_dialer_set(3str) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_dialer_set - set option on byte stream dialer - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_stream_dialer_set(nng_stream_dialer *d, const char *name, const void *data, size_t size); - -int nng_stream_dialer_set_bool(nng_stream_dialer *d, const char *opt, bool 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_alloc.3tls.adoc[`nng_tls_config_alloc()`] -can be passed this way. -+ -NOTE: This form is somewhat special in that the object is generally -not copied, but instead the *pointer* to the object is copied. -Please see the documentation for the specific option for further details. - -`nng_stream_dialer_set_size()`:: -This function is used to configure a size, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_stream_dialer_set_string()`:: -This function is used to pass configure a string. -Strings passed this way must be legal UTF-8 or ASCII strings, terminated -with a `NUL` (`\0`) byte. -(Other constraints may apply as well, see the documentation for each option -for details.) - -`nng_stream_dialer_set_uint64()`:: -This function is used to configure a 64-bit unsigned value/ -This is typically used for identifiers, network numbers, -and similar options. - -`nng_stream_dialer_set_addr()`:: -This function is used to configure a -xref:nng_sockaddr.5.adoc[socket address]. -The value is copied, and thus the caller may discard the supplied -value immediately after this function returns. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The dialer is closed. -`NNG_EINVAL`:: Either _data_ or _size_ are invalid. -`NNG_ENOTSUP`:: The option is not supported. -`NNG_EREADONLY`:: The option may not be modified. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get(3str)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_ipc_options.5.adoc[nng_ipc_options(5)], -xref:nng_tcp_options.5.adoc[nng_tcp_options(5)], -xref:nng_tls_options.5.adoc[nng_tls_options(5)], -xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] \ No newline at end of file diff --git a/docs/man/nng_stream_free.3str.adoc b/docs/man/nng_stream_free.3str.adoc deleted file mode 100644 index 30679458..00000000 --- a/docs/man/nng_stream_free.3str.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= nng_stream_free(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_free - free byte stream - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_stream_free(nng_stream *s); ----- - -== DESCRIPTION - -The `nng_stream_free()` function closes the -xref:nng_stream.5.adoc[byte stream] _s_, -and frees the underlying resources associated with it. - -If any operations are pending, such as -xref:nng_stream_send.3str.adoc[`nng_stream_send()`] -or -xref:nng_stream_recv.3str.adoc[`nng_stream_recv()`], -they will be terminated with an `NNG_ECLOSED` error condition. - -WARNING: It is important that the application ensure that no further accesses -are made to _s_, as the memory backing it will be reclaimed for other uses. - -NOTE: Closing the connection while data is in transmission will likely -lead to loss of that data. -There is no automatic linger or flush to ensure that the socket send buffers -have completely transmitted. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_close.3str.adoc[nng_stream_close(3str)], -xref:nng_stream_recv.3str.adoc[nng_stream_recv(3str)], -xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], -xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/man/nng_stream_get.3str.adoc b/docs/man/nng_stream_get.3str.adoc deleted file mode 100644 index 606fcc09..00000000 --- a/docs/man/nng_stream_get.3str.adoc +++ /dev/null @@ -1,146 +0,0 @@ -= nng_stream_get(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_get - get option from byte stream - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_stream_get(nng_stream *s, const char *opt, void *val, size_t *sizep); - -int nng_stream_get_bool(nng_stream *s, const char *opt, bool *valp); - -int nng_stream_get_int(nng_stream *s, const char *opt, int *valp); - -int nng_stream_get_ms(nng_stream *s, const char *opt, nng_duration *valp); - -int nng_stream_get_ptr(nng_stream *s, const char *opt, void **valp); - -int nng_stream_get_size(nng_stream *s, const char *opt, size_t *valp); - -int nng_stream_get_addr(nng_stream *s, const char *opt, nng_sockaddr *valp); - -int nng_stream_get_string(nng_stream *s, const char *opt, char **valp); - -int nng_stream_get_uint64(nng_stream *s, const char *opt, uint64_t *valp); - ----- - -== DESCRIPTION - -The `nng_stream_get()` functions are used to retrieve option values for the -xref:nng_stream.5.adoc[byte stream] _conn_. - -The actual options that may be retrieved in this way vary. -A number of them are documented in -xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the connected -byte stream _s_. -The forms vary based on the type of the option they take. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_stream_get()`:: -This function is untyped and can be used to retrieve the value of any option. -The caller must store a pointer to a buffer to receive the value in _val_, -and the size of the buffer shall be stored at the location referenced by -_sizep_. -+ -When the function returns, the actual size of the data copied (or that -would have been copied if sufficient space were present) is stored at -the location referenced by _sizep_. -If the caller's buffer is not large enough to hold the entire object, -then the copy is truncated. -Therefore the caller should check for truncation by verifying that the -returned size in _sizep_ does not exceed the original buffer size. -+ -It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. -This can be used to determine the size of the buffer needed to receive -the object. -+ -TIP: It may be easier to use one of the typed forms of this function. - -`nng_stream_get_bool()`:: -This function is for options which take a Boolean (`bool`). - -`nng_stream_get_int()`:: -This function is for options which take an integer (`int`). - -`nng_stream_get_ms()`:: -This function is used to retrieve time -xref:nng_duration.5.adoc[durations] -(such as timeouts), stored as a number of milliseconds. -(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and -the special value ((`NNG_DURATION_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 deleted file mode 100644 index b774a1b9..00000000 --- a/docs/man/nng_stream_listener.5.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= nng_stream_listener(5) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener - byte stream listener - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stream_listener nng_stream_listener; ----- - -== 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 deleted file mode 100644 index f5ffbca5..00000000 --- a/docs/man/nng_stream_listener_accept.3str.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= nng_stream_listener_accept(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_accept - accept incoming byte stream connection - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_stream_listener_accept(nng_stream_listener *l, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_stream_listener_accept()` attempts to accept an incoming byte stream -connection from a remote peer, using the listener _l_. -The operation is completed asynchronously, using _aio_. - -This operation can only be done after the listener is already -xref:nng_stream_listener_listen.3str.adoc[listening]. - -If a connection is successfully established, the _aio_ will have the -resulting -xref:nng_stream.5.adoc[`nng_stream`] object stored as its first output, -which can be retrieved with -xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`]. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECLOSED`:: The listener is closed. -`NNG_ECONNRESET`:: The connection was reset by the peer. -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ESTATE`:: The listener is not not listening. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], -xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)], -xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)], -xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_stream.5.adoc[nng_stream(5)], -xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_listener_alloc.3str.adoc b/docs/man/nng_stream_listener_alloc.3str.adoc deleted file mode 100644 index 966866ba..00000000 --- a/docs/man/nng_stream_listener_alloc.3str.adoc +++ /dev/null @@ -1,70 +0,0 @@ -= nng_stream_listener_alloc(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_alloc - allocate byte stream listener - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_stream_listener_alloc(nng_stream_listener **lp, const char *addr); - -int nng_stream_listener_alloc_url(nng_stream_listener **lp, const nng_url *url); ----- - -== DESCRIPTION - -These functions allocates a listener for byte streams. -Listeners create -xref:nng_stream.5.adoc[`nng_stream`] objects by accepting incoming -connections, via the -xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`] -function. - -The first form, `nng_stream_listener_alloc()`, connects to the address -specified by _addr_, which should be a string representing a URL. - -The second form, `nng_stream_listener_alloc_url()`, takes a pre-parsed -or pre-constructed -xref:nng_url.5.adoc[`nng_url`] object to determine the remote address. - -These functions may support different URL schemes, such as -`ipc://`, `tcp://`, `tls+tcp://`, or `ws://`. - -Both forms store the listener in the location referenced by _lp_. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. -`NNG_ENOTSUP`:: The URL scheme is not supported by the implementation. -`NNG_EADDRINVAL`:: The URL requested is invalid. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)] -xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)] -xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)] -xref:nng_stream_listener_get.3str.adoc[nng_stream_listener_get(3str)] -xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)] -xref:nng_stream_listener_set.3str.adoc[nng_stream_listener_set(3str)] -xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_listener_close.3str.adoc b/docs/man/nng_stream_listener_close.3str.adoc deleted file mode 100644 index a810509e..00000000 --- a/docs/man/nng_stream_listener_close.3str.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_stream_listener_close(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_close - close byte stream listener - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_stream_listener_close(nng_stream_listener *l); ----- - -== DESCRIPTION - -The `nng_stream_listener_close()` function closes the supplied connected byte -stream listener _l_, -but does not free the underlying resources associated with it. - -If any -xref:nng_stream_listener_accept.3str.adoc[accept] -operations using _d_ are -in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -Furthermore any future accesses to the listener _l_ will also result in -`NNG_ECLOSED`. - -NOTE: This function does not release the memory for the listener, so the -application should still free the memory using -xref:nng_stream_listener_free.3str.adoc[`nng_stream_listener_free()`] -once it is certain that nothing else is using it. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], -xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], -xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)], -xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_listener_free.3str.adoc b/docs/man/nng_stream_listener_free.3str.adoc deleted file mode 100644 index aecd8895..00000000 --- a/docs/man/nng_stream_listener_free.3str.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= nng_stream_listener_free(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions - -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_free - free byte stream listener - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_stream_listener_free(nng_stream_listener *)l; ----- - -== DESCRIPTION - -The `nng_stream_listener_free()` function closes the supplied -byte stream listener _l_, -and frees the underlying resources associated with it. - -If any -xref:nng_stream_listener_accept.3str.adoc[accept] operations using __l are -in progress, they will be terminated with an `NNG_ECLOSED` error condition. - -WARNING: It is important that the application ensure that no further accesses -are made to _l_, as the memory backing it will be reclaimed for other uses. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], -xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], -xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)], -xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_listener_get.3str.adoc b/docs/man/nng_stream_listener_get.3str.adoc deleted file mode 100644 index 927e36a8..00000000 --- a/docs/man/nng_stream_listener_get.3str.adoc +++ /dev/null @@ -1,144 +0,0 @@ -= nng_stream_listener_get(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_get - get option from byte stream listener - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_stream_listener_get(nng_stream_listener *l, const char *opt, void *val, size_t *sizep); - -int nng_stream_listener_get_bool(nng_stream_listener *l, const char *opt, bool *valp); - -int nng_stream_listener_get_int(nng_stream_listener *l, const char *opt, int *valp); - -int nng_stream_listener_get_ms(nng_stream_listener *l, const char *opt, nng_duration *valp); - -int nng_stream_listener_get_ptr(nng_stream_listener *l, const char *opt, void **valp); - -int nng_stream_listener_get_size(nng_stream_listener *l, const char *opt, size_t *valp); - -int nng_stream_listener_get_addr(nng_stream_listener *l, const char *opt, nng_sockaddr *valp); - -int nng_stream_listener_get_string(nng_stream_listener *l, const char *opt, char **valp); - -int nng_stream_listener_get_uint64(nng_stream_listener *l, const char *opt, uint64_t *valp); ----- - -== DESCRIPTION - - -The `nng_stream_listener_get()` functions are used to retrieve option values -for the -xref:nng_stream_listener.5.adoc[byte stream listener] _l_. - -The actual options that may be retrieved in this way vary. -A number of them are documented in -xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the connected -byte stream listener _l_. -The forms vary based on the type of the option they take. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_stream_listener_get()`:: -This function is untyped and can be used to retrieve the value of any option. -The caller must store a pointer to a buffer to receive the value in _val_, -and the size of the buffer shall be stored at the location referenced by -_sizep_. -+ -When the function returns, the actual size of the data copied (or that -would have been copied if sufficient space were present) is stored at -the location referenced by _sizep_. -If the caller's buffer is not large enough to hold the entire object, -then the copy is truncated. -Therefore the caller should check for truncation by verifying that the -returned size in _sizep_ does not exceed the original buffer size. -+ -It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. -This can be used to determine the size of the buffer needed to receive -the object. -+ -TIP: It may be easier to use one of the typed forms of this function. - -`nng_stream_listener_get_bool()`:: -This function is for options which take a Boolean (`bool`). - -`nng_stream_listener_get_int()`:: -This function is for options which take an integer (`int`). - -`nng_stream_listener_get_ms()`:: -This function is used to retrieve time -xref:nng_duration.5.adoc[durations] -(such as timeouts), stored as a number of milliseconds. -(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and -the special value ((`NNG_DURATION_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 deleted file mode 100644 index e8473b52..00000000 --- a/docs/man/nng_stream_listener_listen.3str.adoc +++ /dev/null @@ -1,66 +0,0 @@ -= nng_stream_listener_listen(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_listen - bind listener to configured address - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_stream_listener_listen(nng_stream_listener *l); ----- - -== DESCRIPTION - -The `nng_stream_listener_listen()` attempts to bind the listener _l_ -to the local address specified when the listener was created. - -This must generally be done before accepting incoming connections using -xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`]. - -For some transports this will also perform other actiosn. For example, -with TCP listeners it will configure the -underlying port into passive mode, ready to -accept an incoming connection, and established a listen queue -for receiving incoming connections. - -If binding the listener requires allocation of an address (for example -when a TCP port number of zero is specified, indicating that an -ephemeral port should be used), this operation will allocate that -resource. -This can permit retrieval of the selected address using -xref:nng_stream_listener_get.3str.adoc[`nng_stream_listener_get()`], -typically with the -xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`] option. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EADDRINUSE`:: The address is already in use. -`NNG_EADDRINVAL`:: The address is invalid or unavailable. -`NNG_ECLOSED`:: The listener has been closed. -`NNG_ESTATE`:: The listener is already bound. - -== SEE ALSO - -[.text-left] -xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/man/nng_stream_listener_set.3str.adoc b/docs/man/nng_stream_listener_set.3str.adoc deleted file mode 100644 index ccabe5ca..00000000 --- a/docs/man/nng_stream_listener_set.3str.adoc +++ /dev/null @@ -1,133 +0,0 @@ -= nng_stream_listener_set(3str) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_listener_set - set option on byte stream listener - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_stream_listener_set(nng_stream_listener *l, const char *name, const void *data, size_t size); - -int nng_stream_listener_set_bool(nng_stream_listener *l, const char *opt, bool 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_alloc.3tls.adoc[`nng_tls_config_alloc()`] -can be passed this way. -+ -NOTE: This form is somewhat special in that the object is generally -not copied, but instead the *pointer* to the object is copied. -Please see the documentation for the specific option for further details. - -`nng_stream_listener_set_size()`:: -This function is used to configure a size, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_stream_listener_set_string()`:: -This function is used to pass configure a string. -Strings passed this way must be legal UTF-8 or ASCII strings, terminated -with a `NUL` (`\0`) byte. -(Other constraints may apply as well, see the documentation for each option -for details.) - -`nng_stream_listener_set_uint64()`:: -This function is used to configure a 64-bit unsigned value/ -This is typically used for identifiers, network numbers, -and similar options. - -`nng_stream_listener_set_addr()`:: -This function is used to configure a -xref:nng_sockaddr.5.adoc[socket address]. -The value is copied, and thus the caller may discard the supplied -value immediately after this function returns. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The listener is closed. -`NNG_EINVAL`:: Either _data_ or _size_ are invalid. -`NNG_ENOTSUP`:: The option is not supported. -`NNG_EREADONLY`:: The option may not be modified. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_listener_get.3str.adoc[nng_stream_listener_get(3str)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_ipc_options.5.adoc[nng_ipc_options(5)], -xref:nng_tcp_options.5.adoc[nng_tcp_options(5)], -xref:nng_tls_options.5.adoc[nng_tls_options(5)], -xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] \ No newline at end of file diff --git a/docs/man/nng_stream_recv.3str.adoc b/docs/man/nng_stream_recv.3str.adoc deleted file mode 100644 index 148be978..00000000 --- a/docs/man/nng_stream_recv.3str.adoc +++ /dev/null @@ -1,74 +0,0 @@ -= nng_stream_recv(3str) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_recv - receive from byte stream - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_stream_recv(nng_stream *s, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_stream_recv()` function starts an asynchronous receive from the -xref:nng_stream.5.adoc[byte stream] _s_ -into the scatter/gather vector located in the -asynchronous I/O structure _aio_. - -NOTE: The -xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] function must have been -called first, to set the scatter/gather vector for _aio_. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, -and the final result may be obtained via -xref:nng_aio_result.3.adoc[`nng_aio_result()`]. -That result will either be zero or an error code. - -The I/O operation completes as soon as at least one byte has been -received, or an error has occurred. -Therefore, the number of bytes read may be less than requested. -The actual number of bytes read can be determined with -xref:nng_aio_count.3.adoc[`nng_aio_count()`]. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_ECONNSHUT`:: Remote peer shutdown after sending data. -`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_count.3.adoc[nng_aio_count(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_close.3str.adoc[nng_stream_close(3str)], -xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], -xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/man/nng_stream_send.3str.adoc b/docs/man/nng_stream_send.3str.adoc deleted file mode 100644 index 5a53e63c..00000000 --- a/docs/man/nng_stream_send.3str.adoc +++ /dev/null @@ -1,74 +0,0 @@ -= nng_stream_send(3str) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_send - send to byte stream - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_stream_send(nng_stream *s, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_stream_send()` function starts an asynchronous send over the -xref:nng_stream.5.adoc[byte stream] _s_ -from the scatter/gather vector located in the -asynchronous I/O structure _aio_. - -NOTE: The -xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] -function must have been -called first, to set the scatter/gather vector for _aio_. - -This function returns immediately, with no return value. -Completion of the operation is signaled via the _aio_, and the final -result may be obtained via -xref:nng_aio_result.3.adoc[`nng_aio_result()`]. -That result will either be zero or an error code. - -The I/O operation completes as soon as at least one byte has been -sent, or an error has occurred. -Therefore, the number of bytes sent may be less than requested. -The actual number of bytes sent can be determined with -xref:nng_aio_count.3.adoc[`nng_aio_count()`]. - -== RETURN VALUES - -None. - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was canceled. -`NNG_ECLOSED`:: The connection was closed. -`NNG_ECONNRESET`:: The peer closed the connection. -`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. -`NNG_ENOMEM`:: Insufficient free memory to perform the operation. -`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. - -== SEE ALSO - -[.text-left] -xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], -xref:nng_aio_count.3.adoc[nng_aio_count(3)], -xref:nng_aio_result.3.adoc[nng_aio_result(3)], -xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_stream_close.3str.adoc[nng_stream_close(3str)], -xref:nng_stream_recv.3str.adoc[nng_stream_recv(3str)], -xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/man/nng_stream_set.3str.adoc b/docs/man/nng_stream_set.3str.adoc deleted file mode 100644 index e4a82a1a..00000000 --- a/docs/man/nng_stream_set.3str.adoc +++ /dev/null @@ -1,133 +0,0 @@ -= nng_stream_set(3str) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// Copyright 2019 Devolutions -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stream_set - set option on byte stream - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_stream_set(nng_stream *s, const char *name, const void *data, size_t size); - -int nng_stream_set_bool(nng_stream *s, const char *opt, bool 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_alloc.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_register.3.adoc b/docs/man/nng_tcp_register.3.adoc deleted file mode 100644 index 3da671a9..00000000 --- a/docs/man/nng_tcp_register.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_tcp_register(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_register - register tcp transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_tcp_register(void); ----- - -== DESCRIPTION - -The `nng_tcp_register()` function registers the -((_tcp_ transport))(((transport, _tcp_))) for use. - -NOTE: This function is deprecated, and may be removed from a future release. -It is no longer necessary to explicitly register transports. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_tcp.7.adoc[nng_tcp(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_tls_register.3.adoc b/docs/man/nng_tls_register.3.adoc deleted file mode 100644 index bfe27e05..00000000 --- a/docs/man/nng_tls_register.3.adoc +++ /dev/null @@ -1,44 +0,0 @@ -= nng_tls_register(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_register - register tls transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_tls_register(void); ----- - -== DESCRIPTION - -The `nng_tls_register()` function registers the -((_tls_ transport))(((transport, _tls_))) for use. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_tls.7.adoc[nng_tls(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ws_register.3.adoc b/docs/man/nng_ws_register.3.adoc deleted file mode 100644 index 7a9cc1f3..00000000 --- a/docs/man/nng_ws_register.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_ws_register(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ws_register - register WebSocket transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_ws_register(void); ----- - -== DESCRIPTION - -The `nng_ws_register()` function registers the -((_ws_ transport))(((transport, _ws_))) for use. - -NOTE: This function is deprecated, and may be removed from a future release. -It is no longer necessary to explicitly register transports. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_ws.7.adoc[nng_ws(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_wss_register.3.adoc b/docs/man/nng_wss_register.3.adoc deleted file mode 100644 index 856fe1c0..00000000 --- a/docs/man/nng_wss_register.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_wss_register(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_wss_register - register WebSocket secure transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_wss_register(void); ----- - -== DESCRIPTION - -The `nng_wss_register()` function registers the -((_wss_ transport))(((transport, _wss_))) for use. - -NOTE: This function is deprecated, and may be removed from a future release. -It is no longer necessary to explicitly register transports. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_ws.7.adoc[nng_ws(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_zt_register.3.adoc b/docs/man/nng_zt_register.3.adoc deleted file mode 100644 index 9c4a4ac4..00000000 --- a/docs/man/nng_zt_register.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_zt_register(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_zt_register - register ZeroTier transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_zt_register(void); ----- - -== DESCRIPTION - -The `nng_zt_register()` function registers the -((_zt_ transport))(((transport, _zt_))) for use. - -NOTE: This function is deprecated, and may be removed from a future release. -It is no longer necessary to explicitly register transports. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_zerotier.7.adoc[nng_zerotier(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/book.toml b/docs/reference/book.toml index aeca51c3..d74117ea 100644 --- a/docs/reference/book.toml +++ b/docs/reference/book.toml @@ -15,6 +15,8 @@ fold.level = 1 [preprocessor.indexing.see_instead] # "*PUSH* (protocol)" = "protocol, *PUSH*" +"URI" = "URI" +"option" = "Options" [preprocessor.indexing.nest_under] "body" = "message" @@ -38,11 +40,25 @@ fold.level = 1 "*ws*" = "transport" "*wss*" = "transport" +"`abstract://`" = "URI" "`inproc://`" = "URI" "`ipc://`" = "URI" "`tls+tcp://`" = "URI" "`tcp://`" = "URI" +"`unix://`" = "URI" "`ws://`" = "URI" "`wss://`" = "URI" +"`NNG_OPT_LOCADDR`" = "option" +"`NNG_OPT_REMADDR`" = "option" +"`NNG_OPT_PEER_GID`" = "option" +"`NNG_OPT_PEER_PID`" = "option" +"`NNG_OPT_PEER_UID`" = "option" +"`NNG_OPT_SUB_PREFNEW`" = "option" +"`NNG_OPT_SUB_SUBSCRIBE`" = "option" +"`NNG_OPT_SUB_UNSUBSCRIBE`" = "option" +"`NNG_OPT_SURVEYOR_SURVEYTIME`" = "option" +"`NNG_OPT_REQ_RESENDTIME`" = "option" +"`NNG_OPT_REQ_RESENDTICK`" = "option" + [preprocessor.alerts] diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index 82187252..e81fec99 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -19,6 +19,7 @@ - [Transports](tran/index.md) + - [IPC](tran/ipc.md) - [INPROC](tran/inproc.md) - [TCP](tran/tcp.md) diff --git a/docs/reference/src/old/nng_dialer_getopt.3.adoc b/docs/reference/src/old/nng_dialer_getopt.3.adoc new file mode 100644 index 00000000..a4083819 --- /dev/null +++ b/docs/reference/src/old/nng_dialer_getopt.3.adoc @@ -0,0 +1,149 @@ += nng_dialer_getopt(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_dialer_getopt - get dialer option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_dialer_getopt(nng_dialer d, const char *opt, void *val, size_t *valszp); + +int nng_dialer_getopt_bool(nng_dialer d, const char *opt, bool *bvalp); + +int nng_dialer_getopt_int(nng_dialer d, const char *opt, int *ivalp); + +int nng_dialer_getopt_ms(nng_dialer d, const char *opt, nng_duration *durp); + +int nng_dialer_getopt_ptr(nng_dialer d, const char *opt, void **ptr); + +int nng_dialer_getopt_size(nng_dialer d, const char *opt, size_t *zp); + +int nng_dialer_getopt_sockaddr(nng_dialer d, const char *opt, nng_sockaddr *sap); + +int nng_dialer_getopt_string(nng_dialer d, const char *opt, char **strp); + +int nng_dialer_getopt_uint64(nng_dialer d, const char *opt, uint64_t *u64p); + +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_dialer_get.3.adoc[nng_dialer_get]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, dialer))) +The `nng_dialer_getopt()` functions are used to retrieve option values for +the xref:nng_dialer.5.adoc[dialer] _d_. +The actual options that may be retrieved in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific options are documented with the transports themselves. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the 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_dialer_getopt()`:: +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_. + + + +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 validate that the returned size in _valszp_ does not +exceed the original buffer size to check for truncation. + + + +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_dialer_getopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The value will be stored at _bvalp_. + +`nng_dialer_getopt_int()`:: +This function is for options which take an integer (`int`). +The value will be stored at _ivalp_. + +`nng_dialer_getopt_ms()`:: +This function is used to retrieve time xref:nng_duration.5.adoc[durations] +(such as timeouts), stored in _durp_ as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) + +`nng_dialer_getopt_ptr()`:: +This function is used to retrieve a pointer, _ptr_, to structured data. +The data referenced by _ptr_ 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. + +`nng_dialer_getopt_size()`:: +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_dialer_getopt_sockaddr()`:: +This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] +into the value referenced by _sap_. + +`nng_dialer_getopt_string()`:: +This function is used to retrieve a string into _strp_. +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_dialer_getopt_uint64()`:: +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. + +== RETURN VALUES + +These functions returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. +`NNG_EINVAL`:: Size of destination _val_ too small for object. +`NNG_ENOMEM`:: Insufficient memory exists. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +[.text-left] +xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] +xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)] +xref:nng_strdup.3.adoc[nng_strdup(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_strfree.3.adoc[nng_strfree(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_dialer_setopt.3.adoc b/docs/reference/src/old/nng_dialer_setopt.3.adoc new file mode 100644 index 00000000..3aaff1eb --- /dev/null +++ b/docs/reference/src/old/nng_dialer_setopt.3.adoc @@ -0,0 +1,134 @@ += nng_dialer_setopt(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_dialer_setopt - set dialer option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_dialer_setopt(nng_dialer d, const char *opt, const void *val, + size_t valsz); + +int nng_dialer_setopt_bool(nng_dialer d, const char *opt, bool bval); + +int nng_dialer_setopt_int(nng_dialer d, const char *opt, int ival); + +int nng_dialer_setopt_ms(nng_dialer d, const char *opt, nng_duration dur); + +int nng_dialer_setopt_ptr(nng_dialer d, const char *opt, void *ptr); + +int nng_dialer_setopt_size(nng_dialer d, const char *opt, size_t z); + +int nng_dialer_setopt_string(nng_dialer d, const char *opt, const char *str); + +int nng_dialer_setopt_uint64(nng_dialer d, const char *opt, uint64_t u64); + +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_dialer_set.3.adoc[nng_dialer_set]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, dialer))) +The `nng_dialer_setopt()` functions are used to configure options for +the xref:nng_dialer.5.adoc[dialer] _d_. +The actual options that may be configured in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific options are documented with the +transports themselves. + +NOTE: Once a dialer has started, it is generally not possible to change +its configuration. + +=== Forms + +In all of these forms, the option _opt_ is configured on the dialer _d_. + +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_dialer_setopt()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ 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_dialer_setopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The _bval_ is passed to the option. + +`nng_dialer_setopt_int()`:: +This function is for options which take an integer (`int`). +The _ival_ is passed to the option. + +`nng_dialer_setopt_ms()`:: +This function is used to configure time durations (such as timeouts) using +type xref:nng_duration.5.adoc[`nng_duration`]. +The duration _dur_ is an integer number of milliseconds. + +`nng_dialer_setopt_ptr()`:: +This function is used to pass a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed by other functions. +For example, TLS configuration objects created with +(xref:nng_tls_config_alloc.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. + +`nng_dialer_setopt_size()`:: +This function is used to configure a size, _z_, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_dialer_setopt_string()`:: +This function is used to pass configure a string, _str_. +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_dialer_setopt_uint64()`:: +This function is used to configure a 64-bit unsigned value, _u64_. +This is typically used for options related to identifiers, network numbers, +and such. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. +`NNG_EINVAL`:: The value being passed is invalid. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EREADONLY`:: The option _opt_ is read-only. +`NNG_ESTATE`:: The dialer _d_ is already started. + +== SEE ALSO + +[.text-left] +xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] +xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_dialer.5.adoc[nng_dialer(5)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_getopt.3.adoc b/docs/reference/src/old/nng_getopt.3.adoc new file mode 100644 index 00000000..364d8f71 --- /dev/null +++ b/docs/reference/src/old/nng_getopt.3.adoc @@ -0,0 +1,145 @@ += nng_getopt(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_getopt - get socket option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_getopt(nng_socket s, const char *opt, void *val, size_t *valszp); + +int nng_getopt_bool(nng_socket s, const char *opt, bool *bvalp); + +int nng_getopt_int(nng_socket s, const char *opt, int *ivalp); + +int nng_getopt_ms(nng_socket s, const char *opt, nng_duration *durp); + +int nng_getopt_ptr(nng_socket s, const char *opt, void **ptr); + +int nng_getopt_size(nng_socket s, const char *opt, size_t *zp); + +int nng_getopt_string(nng_socket s, const char *opt, char **strp); + +int nng_getopt_uint64(nng_socket s, const char *opt, uint64_t *u64p); + +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_socket_get.3.adoc[nng_socket_get]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, socket))) +The `nng_getopt()` functions are used to retrieve option values for +the xref:nng_socket.5.adoc[socket] _s_. +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)]. + +Additionally transport-specific options and protocol-specific options are +documented with the transports and protocols themselves. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the socket _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_getopt()`:: +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_. ++ +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. ++ +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 _bvalp_. + +`nng_getopt_int()`:: +This function is for options which take an integer (`int`). +The value will be stored at _ivalp_. + +`nng_getopt_ms()`:: +This function is used to retrieve time xref:nng_duration.5.adoc[durations] +(such as timeouts), stored in _durp_ as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) + +`nng_getopt_ptr()`:: +This function is used to retrieve a pointer, _ptr_, to structured data. +The data referenced by _ptr_ 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. + +`nng_getopt_size()`:: +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_getopt_string()`:: +This function is used to retrieve a string into _strp_. +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_getopt_uint64()`:: +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. +`NNG_EINVAL`:: Size of destination _val_ too small for object. +`NNG_ENOMEM`:: Insufficient memory exists. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +[.text-left] +xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)], +xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)], +xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng_setopt.3.adoc[nng_setopt(3)], +xref:nng_strdup.3.adoc[nng_strdup(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_strfree.3.adoc[nng_strfree(3)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_inproc_register.3.adoc b/docs/reference/src/old/nng_inproc_register.3.adoc new file mode 100644 index 00000000..8379a4e8 --- /dev/null +++ b/docs/reference/src/old/nng_inproc_register.3.adoc @@ -0,0 +1,47 @@ += nng_inproc_register(3) +// +// Copyright 2021 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_inproc_register - register inproc transport + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_inproc_register(void); +---- + +== DESCRIPTION + +The `nng_inproc_register()` function registers the +((_inproc_ transport))(((transport, _inproc_))) for use. + +NOTE: This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The transport is not supported. + +== SEE ALSO + +[.text-left] +xref:nng_inproc.7.adoc[nng_inproc(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_ipc_register.3.adoc b/docs/reference/src/old/nng_ipc_register.3.adoc new file mode 100644 index 00000000..64da4b00 --- /dev/null +++ b/docs/reference/src/old/nng_ipc_register.3.adoc @@ -0,0 +1,47 @@ += nng_ipc_register(3) +// +// Copyright 2021 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_ipc_register - register ipc transport + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_ipc_register(void); +---- + +== DESCRIPTION + +The `nng_ipc_register()` function registers the +((_ipc_ transport))(((transport, _ipc_))) for use. + +NOTE: This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The transport is not supported. + +== SEE ALSO + +[.text-left] +xref:nng_ipc.7.adoc[nng_ipc(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_listener_getopt.3.adoc b/docs/reference/src/old/nng_listener_getopt.3.adoc new file mode 100644 index 00000000..828f440d --- /dev/null +++ b/docs/reference/src/old/nng_listener_getopt.3.adoc @@ -0,0 +1,150 @@ += nng_listener_getopt(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_listener_getopt - get listener option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_listener_getopt(nng_listener l, const char *opt, void *val, size_t *valszp); + +int nng_listener_getopt_bool(nng_listener l, const char *opt, bool *bvalp); + +int nng_listener_getopt_int(nng_listener l, const char *opt, int *ivalp); + +int nng_listener_getopt_ms(nng_listener l, const char *opt, nng_duration *durp); + +int nng_listener_getopt_ptr(nng_listener l, const char *opt, void **ptr); + +int nng_listener_getopt_size(nng_listener l, const char *opt, size_t *zp); + +int nng_listener_getopt_sockaddr(nng_listener l, const char *opt, nng_sockaddr *sap); + +int nng_listener_getopt_string(nng_listener l, const char *opt, char **strp); + +int nng_listener_getopt_uint64(nng_listener l, const char *opt, uint64_t *u64p); + +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_listener_get.3.adoc[nng_listener_get]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, listener))) +The `nng_listener_getopt()` functions are used to retrieve option values for +the xref:nng_listener.5.adoc[listener] _l_. +The actual options that may be retrieved in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific options +are documented with the transports themselves. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the 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_listener_getopt()`:: +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_. + + + +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 validate that the returned size in _valszp_ does not +exceed the original buffer size to check for truncation. + + + +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_listener_getopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The value will be stored at _bvalp_. + +`nng_listener_getopt_int()`:: +This function is for options which take an integer (`int`). +The value will be stored at _ivalp_. + +`nng_listener_getopt_ms()`:: +This function is used to retrieve time xref:nng_duration.5.adoc[durations] +(such as timeouts), stored in _durp_ as a number of milliseconds. + +`nng_listener_getopt_ptr()`:: +This function is used to retrieve a pointer, _ptr_, to structured data. +The data referenced by _ptr_ 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. + +`nng_listener_getopt_size()`:: +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_listener_getopt_sockaddr()`:: +This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] +into the value referenced by _sap_. + +`nng_listener_getopt_string()`:: +This function is used to retrieve a string into _strp_. +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_listener_getopt_uint64()`:: +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. +`NNG_EINVAL`:: Size of destination _val_ too small for object. +`NNG_ENOMEM`:: Insufficient memory exists. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +[.text-left] +xref:nng_listen.3.adoc[nng_listen(3)], +xref:nng_listener_create.3.adoc[nng_listener_create(3)] +xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)] +xref:nng_getopt.3.adoc[nng_getopt(3)], +xref:nng_strdup.3.adoc[nng_strdup(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_strfree.3.adoc[nng_strfree(3)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_listener_setopt.3.adoc b/docs/reference/src/old/nng_listener_setopt.3.adoc new file mode 100644 index 00000000..25411adc --- /dev/null +++ b/docs/reference/src/old/nng_listener_setopt.3.adoc @@ -0,0 +1,136 @@ += nng_listener_setopt(3) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_listener_setopt - set listener option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_listener_setopt(nng_listener l, const char *opt, const void *val, + size_t valsz); + +int nng_listener_setopt_bool(nng_listener l, const char *opt, bool bval); + +int nng_listener_setopt_int(nng_listener l, const char *opt, int ival); + +int nng_listener_setopt_ms(nng_listener l, const char *opt, nng_duration dur); + +int nng_listener_setopt_ptr(nng_listener l, const char *opt, void *ptr); + +int nng_listener_setopt_size(nng_listener l, const char *opt, size_t z); + +int nng_listener_setopt_string(nng_listener l, const char *opt, const char *str); + +int nng_listener_setopt_uint64(nng_listener l, const char *opt, uint64_t u64); + +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_listener_set.3.adoc[nng_listener_set]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, listener))) +The `nng_listener_setopt()` functions are used to configure options for +the xref:nng_listener.5.adoc[listener] _l_. +The actual options that may be configured in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. + +Additionally some transport-specific options +are documented with the transports themselves. + +NOTE: Once a listener has started, it is generally not possible to change +its configuration. + +=== Forms + +In all of these forms, the option _opt_ is configured on the listener _l_. + +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. + +TIP: It may be easier to use one of the typed forms of this function. + +`nng_listener_setopt()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. + +`nng_listener_setopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The _bval_ is passed to the option. + +`nng_listener_setopt_int()`:: +This function is for options which take an integer (`int`). +The _ival_ is passed to the option. + +`nng_listener_setopt_ms()`:: +This function is used to configure time durations (such as timeouts) using +type xref:nng_duration.5.adoc[`nng_duration`]. +The duration _dur_ is an integer number of milliseconds. + +`nng_listener_setopt_ptr()`:: +This function is used to pass a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed by other functions. +For example, TLS configuration objects created with +(xref:nng_tls_config_alloc.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. + +`nng_listener_setopt_size()`:: +This function is used to configure a size, _z_, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_listener_setopt_string()`:: +This function is used to pass configure a string, _str_. +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_listener_setopt_uint64()`:: +This function is used to configure a 64-bit unsigned value, _u64_. +This is typically used for options related to identifiers, network numbers, +and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. +`NNG_EINVAL`:: The value being passed is invalid. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EREADONLY`:: The option _opt_ is read-only. +`NNG_ESTATE`:: The listener _l_ is already started. + +== SEE ALSO + +[.text-left] +xref:nng_listen.3.adoc[nng_listen(3)], +xref:nng_listener_create.3.adoc[nng_listener_create(3)] +xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)] +xref:nng_setopt.3.adoc[nng_setopt(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_listener.5.adoc[nng_listener(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_pipe_getopt.3.adoc b/docs/reference/src/old/nng_pipe_getopt.3.adoc new file mode 100644 index 00000000..648abbcc --- /dev/null +++ b/docs/reference/src/old/nng_pipe_getopt.3.adoc @@ -0,0 +1,155 @@ += nng_pipe_getopt(3) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_pipe_getopt - get pipe option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_pipe_getopt(nng_pipe p, const char *opt, void *val, size_t *valszp); + +int nng_pipe_getopt_bool(nng_pipe p, const char *opt, bool *bvalp); + +int nng_pipe_getopt_int(nng_pipe p, const char *opt, int *ivalp); + +int nng_pipe_getopt_ms(nng_pipe p, const char *opt, nng_duration *durp); + +int nng_pipe_getopt_ptr(nng_pipe p, const char *opt, void **ptr); + +int nng_pipe_getopt_sockaddr(nng_pipe p, const char *opt, nng_sockaddr *sap); + +int nng_pipe_getopt_string(nng_pipe p, const char *opt, char **strp); + +int nng_pipe_getopt_size(nng_pipe p, const char *opt, size_t *zp); + +int nng_pipe_getopt_uint64(nng_pipe p, const char *opt, uint64_t *u64p); + +---- + +== DESCRIPTION + +NOTE: These functions are deprecated. Please see xref:nng_pipe_get.3.adoc[nng_pipe_get]. + +(((options, pipe))) +The `nng_pipe_getopt()` functions are used to retrieve option values for +the xref:nng_pipe.5.adoc[pipe] _p_. +The actual options that may be retrieved in this way +vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. +Additionally some transport-specific options and protocol-specific options are +documented with the transports and protocols themselves. + +NOTE: All options on a pipe are read-only values. +Modification of options may be done before the pipe is created using +xref:nng_listener_setopt.3.adoc[`nng_listener_setopt()`] or +xref:nng_dialer_getopt.3.adoc[`nng_dialer_setopt()`]. + +Any option that is set on a dialer or listener will normally be retrievable +from pipes created by that dialer or listener. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the pipe _p_. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_pipe_getopt()`:: +This is untyped, and can be used to retrieve the value of any option. +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_. + + + +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 +size returned 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_pipe_getopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The value will be stored at _bvalp_. + +`nng_pipe_getopt_int()`:: +This function is for options which take an integer (`int`). +The value will be stored at _ivalp_. + +`nng_pipe_getopt_ms()`:: +This function is used to retrieve time durations +(xref:nng_duration.5.adoc[`nng_duration`]) in milliseconds, which are stored in +_durp_. + +`nng_pipe_getopt_ptr()`:: +This function is used to retrieve a pointer, _ptr_, to structured data. +The data referenced by _ptr_ 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. + +`nng_pipe_getopt_size()`:: +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. + +`nng_pipe_getopt_sockaddr()`:: +This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] +into _sap_. + +`nng_pipe_getopt_string()`:: +This function is used to retrieve a string into _strp_. +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_pipe_getopt_uint64()`:: +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options +related to identifiers, network numbers, and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EBADTYPE`:: Incorrect type for option. +`NNG_ECLOSED`:: Parameter _p_ does not refer to an open pipe. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_ENOMEM`:: Insufficient memory exists. +`NNG_EINVAL`:: Size of destination _val_ too small for object. +`NNG_EWRITEONLY`:: The option _opt_ is write-only. + +== SEE ALSO + +[.text-left] +xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)] +xref:nng_getopt.3.adoc[nng_getopt(3)], +xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)] +xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe(3)] +xref:nng_strdup.3.adoc[nng_strdup(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_strfree.3.adoc[nng_strfree(3)], +xref:nng_duration.5.adoc[nng_duration(5)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_pipe.5.adoc[nng_pipe(5)], +xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_setopt.3.adoc b/docs/reference/src/old/nng_setopt.3.adoc new file mode 100644 index 00000000..6c21cf95 --- /dev/null +++ b/docs/reference/src/old/nng_setopt.3.adoc @@ -0,0 +1,127 @@ += nng_setopt(3) + +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. + +== NAME + +nng_setopt - set socket option + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_setopt(nng_socket s, const char *opt, const void *val, size_t valsz); + +int nng_setopt_bool(nng_socket s, const char *opt, bool bval); + +int nng_setopt_int(nng_socket s, const char *opt, int ival); + +int nng_setopt_ms(nng_socket s, const char *opt, nng_duration dur); + +int nng_setopt_ptr(nng_socket s, const char *opt, void *ptr); + +int nng_setopt_size(nng_socket s, const char *opt, size_t z); + +int nng_setopt_string(nng_socket s, const char *opt, const char *str); + +int nng_setopt_uint64(nng_socket s, const char *opt, uint64_t u64); + +---- + +== DESCRIPTION + +IMPORTANT: These functions are deprecated. Please see xref:nng_socket_set.3.adoc[nng_socket_set]. +They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. + +(((options, socket))) +The `nng_setopt()` functions are used to configure options for +the socket _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_setopt()`:: +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ 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_setopt_bool()`:: +This function is for options which take a Boolean (`bool`). +The _bval_ is passed to the option. + +`nng_setopt_int()`:: +This function is for options which take an integer (`int`). +The _ival_ is passed to the option. + +`nng_setopt_ms()`:: +This function is used to configure time durations (such as timeouts) using +type xref:nng_duration.5.adoc[`nng_duration`]. +The duration _dur_ is an integer number of milliseconds. + +`nng_setopt_ptr()`:: +This function is used to pass a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed by other functions. +For example, TLS configuration objects created with +(xref:nng_tls_config_alloc.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. + +`nng_setopt_size()`:: +This function is used to configure a size, _z_, typically for buffer sizes, +message maximum sizes, and similar options. + +`nng_setopt_string()`:: +This function is used to pass configure a string, _str_. +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_setopt_uint64()`:: +This function is used to configure a 64-bit unsigned value, _u64_. +This is typically used for options related to identifiers, network numbers, +and similar. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. +`NNG_EINVAL`:: The value being passed is invalid. +`NNG_ENOTSUP`:: The option _opt_ is not supported. +`NNG_EREADONLY`:: The option _opt_ is read-only. +`NNG_ESTATE`:: The socket is in an inappropriate state for setting this option. + +== SEE ALSO + +[.text-left] +xref:nng_getopt.3.adoc[nng_getopt(3)], +xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)], +xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_options.5.adoc[nng_options(5)], +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_tcp_register.3.adoc b/docs/reference/src/old/nng_tcp_register.3.adoc new file mode 100644 index 00000000..3da671a9 --- /dev/null +++ b/docs/reference/src/old/nng_tcp_register.3.adoc @@ -0,0 +1,47 @@ += nng_tcp_register(3) +// +// Copyright 2021 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_tcp_register - register tcp transport + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_tcp_register(void); +---- + +== DESCRIPTION + +The `nng_tcp_register()` function registers the +((_tcp_ transport))(((transport, _tcp_))) for use. + +NOTE: This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The transport is not supported. + +== SEE ALSO + +[.text-left] +xref:nng_tcp.7.adoc[nng_tcp(7)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_tls_register.3.adoc b/docs/reference/src/old/nng_tls_register.3.adoc new file mode 100644 index 00000000..bfe27e05 --- /dev/null +++ b/docs/reference/src/old/nng_tls_register.3.adoc @@ -0,0 +1,44 @@ += nng_tls_register(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_tls_register - register tls transport + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_tls_register(void); +---- + +== DESCRIPTION + +The `nng_tls_register()` function registers the +((_tls_ transport))(((transport, _tls_))) for use. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The transport is not supported. + +== SEE ALSO + +[.text-left] +xref:nng_tls.7.adoc[nng_tls(7)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_ws_register.3.adoc b/docs/reference/src/old/nng_ws_register.3.adoc new file mode 100644 index 00000000..7a9cc1f3 --- /dev/null +++ b/docs/reference/src/old/nng_ws_register.3.adoc @@ -0,0 +1,47 @@ += nng_ws_register(3) +// +// Copyright 2021 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_ws_register - register WebSocket transport + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_ws_register(void); +---- + +== DESCRIPTION + +The `nng_ws_register()` function registers the +((_ws_ transport))(((transport, _ws_))) for use. + +NOTE: This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The transport is not supported. + +== SEE ALSO + +[.text-left] +xref:nng_ws.7.adoc[nng_ws(7)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_wss_register.3.adoc b/docs/reference/src/old/nng_wss_register.3.adoc new file mode 100644 index 00000000..856fe1c0 --- /dev/null +++ b/docs/reference/src/old/nng_wss_register.3.adoc @@ -0,0 +1,47 @@ += nng_wss_register(3) +// +// Copyright 2021 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_wss_register - register WebSocket secure transport + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_wss_register(void); +---- + +== DESCRIPTION + +The `nng_wss_register()` function registers the +((_wss_ transport))(((transport, _wss_))) for use. + +NOTE: This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The transport is not supported. + +== SEE ALSO + +[.text-left] +xref:nng_ws.7.adoc[nng_ws(7)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/old/nng_zt_register.3.adoc b/docs/reference/src/old/nng_zt_register.3.adoc new file mode 100644 index 00000000..9c4a4ac4 --- /dev/null +++ b/docs/reference/src/old/nng_zt_register.3.adoc @@ -0,0 +1,47 @@ += nng_zt_register(3) +// +// Copyright 2021 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_zt_register - register ZeroTier transport + +== SYNOPSIS + +[source,c] +---- +#include + +int nng_zt_register(void); +---- + +== DESCRIPTION + +The `nng_zt_register()` function registers the +((_zt_ transport))(((transport, _zt_))) for use. + +NOTE: This function is deprecated, and may be removed from a future release. +It is no longer necessary to explicitly register transports. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The transport is not supported. + +== SEE ALSO + +[.text-left] +xref:nng_zerotier.7.adoc[nng_zerotier(7)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md index ea27e96e..5d808e0b 100644 --- a/docs/reference/src/refs.md +++ b/docs/reference/src/refs.md @@ -7,9 +7,11 @@ [msg]: ../msg/index.md [pipe]: ../overview/pipe.md [socket]: ../sock/index.md -[sockadddr]: ../overview/sockaddr.md +[sockaddr]: ../overview/sockaddr.md [sockaddr_in]: ../overview/sockaddr_in.md [sockaddr_in6]: ../overview/sockaddr_in6.md +[sockaddr_ipc]: ../overview/sockaddr_ipc.md +[sockaddr_abstract]: ../overview/sockaddr_abstract.md [raw]: ../overview/raw.md [url]: ../overview/url.md [transport]: ../tran/index.md @@ -147,8 +149,14 @@ [NNG_OPT_SENDBUF]: ../opts/nng_opt_sendbuf.md [NNG_OPT_LOCADDR]: ../opts/nng_opt_locaddr.md [NNG_OPT_REMADDR]: ../api/nng_options.md#NNG_OPT_REMADDR -[NNG_OPT_TCP_KEEPALIVE]: ../api/nng_tcp_options.md#NNG_OPT_TCP_KEEPALIVE -[NNG_OPT_TCP_NODELAY]: ../api/nng_tcp_options.md#NNG_OPT_TCP_NODELAY +[NNG_OPT_TCP_KEEPALIVE]: ../opts/tcp_options.md#NNG_OPT_TCP_KEEPALIVE +[NNG_OPT_TCP_NODELAY]: ../opts/tcp_options.md#NNG_OPT_TCP_NODELAY +[NNG_OPT_IPC_SECURITY_DESCRIPTOR]: ../opts/ipc_options.md +[NNG_OPT_IPC_PERMISSIONS]: ../opts/ipc_options.md +[NNG_OPT_PEER_GID]: ../opts/ipc_options.md +[NNG_OPT_PEER_PID]: ../opts/ipc_options.md +[NNG_OPT_PEER_UID]: ../opts/ipc_options.md +[NNG_OPT_PEER_ZONEID]: ../opts/ipc_options.md [NNG_OPT_URL]: ../api/nng_options.md#NNG_OPT_URL diff --git a/docs/reference/src/stream/nng_stream_close.3str.adoc b/docs/reference/src/stream/nng_stream_close.3str.adoc new file mode 100644 index 00000000..9e7b8d6a --- /dev/null +++ b/docs/reference/src/stream/nng_stream_close.3str.adoc @@ -0,0 +1,65 @@ += nng_stream_close(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_close - close byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_close(nng_stream *s); +---- + +== DESCRIPTION + +The `nng_stream_close()` function closes the +xref:nng_stream.5.adoc[byte stream] _s_. + +If any operations are pending, such as +xref:nng_stream_send.3str.adoc[`nng_stream_send()`] +or +xref:nng_stream_recv.3str.adoc[`nng_stream_recv()`], +they will be terminated with +an `NNG_ECLOSED` error condition. +Also, any new operations will fail with `NNG_ECLOSED` after the connection +is closed. + +NOTE: Closing the connection while data is in transmission will likely +lead to loss of that data. +There is no automatic linger or flush to ensure that the socket send buffers +have completely transmitted. + +NOTE: Closing the connection does not free the resources associated with it. +Once it is certain that no more operations are pending on the connection, +it should be freed with +xref:nng_stream_free.3str.adoc[`nng_stream_free()`]. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_free.3str.adoc[nng_stream_free(3str)], +xref:nng_stream_recv.3str.adoc[nng_stream_recv(3str)], +xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer.5.adoc b/docs/reference/src/stream/nng_stream_dialer.5.adoc new file mode 100644 index 00000000..eef23a3d --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer.5.adoc @@ -0,0 +1,46 @@ += nng_stream_dialer(5) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer - byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct nng_stream_dialer nng_stream_dialer; +---- + +== DESCRIPTION + +(((byte stream, dialer))) +An `nng_stream_dialer` is a handle to a dialer for byte streams, +and is responsible for creating +xref:nng_stream.5.adoc[`nng_stream`] objects (corresponding to connected byte +streams) by connecting to remote peers. + +NOTE: The `nng_stream_dialer` object is used for low-level byte stream +connections, and should not be confused with a high-level +xref:nng_dialer.5.adoc[`nng_dialer`] object. + +== SEE ALSO + +[.text-left] +xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], +xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)], +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], +xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)], +xref:nng_stream.5.adoc[nng_stream(5)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer_alloc.3str.adoc b/docs/reference/src/stream/nng_stream_dialer_alloc.3str.adoc new file mode 100644 index 00000000..0c2db67c --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer_alloc.3str.adoc @@ -0,0 +1,68 @@ += nng_stream_dialer_alloc(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer_alloc - allocate byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_dialer_alloc(nng_stream_dialer **dp, const char *addr); + +int nng_stream_dialer_alloc_url(nng_stream_dialer **dp, const nng_url *url); +---- + +== DESCRIPTION + +These functions allocates a dialer for byte streams. +Dialers create +xref:nng_stream.5.adoc[`nng_stream`] objects by initiating outgoing +connections, via the +xref:nng_stream_dialer_dial.3str.adoc[`nng_stream_dialer_dial()`] function. + +The first form, `nng_stream_dialer_alloc()`, connects to the address +specified by _addr_, which should be a string representing a URL. + +The second form, `nng_stream_dialer_alloc_url()`, takes a pre-parsed +or pre-constructed +xref:nng_url.5.adoc[`nng_url`] object to determine the remote address. + +These functions may support different URL schemes, such as +`ipc://`, `tcp://`, `tls+tcp://`, or `ws://`. + +Both forms store the dialer in the location referenced by _dp_. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: The URL scheme is not supported by the implementation. +`NNG_EADDRINVAL`:: The URL requested is invalid. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)] +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)] +xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)] +xref:nng_stream_dialer_get.3str.adoc[nng_stream_dialer_get(3str)] +xref:nng_stream_dialer_set.3str.adoc[nng_stream_dialer_set(3str)] +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer_close.3str.adoc b/docs/reference/src/stream/nng_stream_dialer_close.3str.adoc new file mode 100644 index 00000000..59d9dec0 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer_close.3str.adoc @@ -0,0 +1,60 @@ += nng_stream_dialer_close(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer_close - close byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_dialer_close(nng_stream_dialer *d); +---- + +== DESCRIPTION + +The `nng_stream_dialer_close()` function closes the supplied byte stream +dialer _d_, +but does not free the underlying resources associated with it. + +If any +xref:nng_stream_dialer_dial.3str.adoc[dial] +operations using _d_ are +in progress, they will be terminated with an `NNG_ECLOSED` error condition. + +Furthermore any future accesses to the dialer _d_ will also result in +`NNG_ECLOSED`. + +NOTE: This function does not release the memory for the dialer, so the +application should still free the memory using +xref:nng_stream_dialer_free.3str.adoc[`nng_stream_dialer_free()`] +once it is certain that nothing else is using it. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], +xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer_dial.3str.adoc b/docs/reference/src/stream/nng_stream_dialer_dial.3str.adoc new file mode 100644 index 00000000..8dcd4ec2 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer_dial.3str.adoc @@ -0,0 +1,65 @@ += nng_stream_dialer_dial(3str) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer_dial - initiate outgoing byte stream connection + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_dialer_dial(nng_stream_dialer *d, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_stream_dialer_dial()` attempts to establish a connection to the +remote peer for the dialer _d_. +The operation is completed asynchronously, using _aio_. + +TIP: The peer address is determined by the address specified using +xref:nng_stream_dialer_alloc.3str.adoc[`nng_stream_dialer_alloc()`] or +xref:nng_stream_dialer_alloc.3str.adoc[`nng_stream_dialer_alloc_url()`]. + +If a connection is successfully established, the _aio_ will have the +resulting +xref:nng_stream.5.adoc[`nng_stream`] object stored as its first output. +(See +xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`].) + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_EADDRINVAL`:: The address specified is invalid. +`NNG_ECANCELED`:: The operation was aborted. +`NNG_ECLOSED`:: The dialer is closed. +`NNG_ECONNREFUSED`:: The connection was refused by the server. +`NNG_ECONNRESET`:: The connection was reset by the server. +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], +xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)], +xref:nng_stream_dialer_free.3str.adoc[nng_stream_dialer_free(3str)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng_stream.5.adoc[nng_stream(5)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer_free.3str.adoc b/docs/reference/src/stream/nng_stream_dialer_free.3str.adoc new file mode 100644 index 00000000..6669ca1e --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer_free.3str.adoc @@ -0,0 +1,54 @@ += nng_stream_dialer_free(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions + +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer_free - free byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_dialer_free(nng_stream_dialer *d); +---- + +== DESCRIPTION + +The `nng_stream_dialer_free()` function closes the supplied +byte stream dialer _d_, +and frees the underlying resources associated with it. + +If any +xref:nng_stream_dialer_dial.3str.adoc[dial] operations using _d_ are +in progress, they will be terminated with an `NNG_ECLOSED` error condition. + +WARNING: It is important that the application ensure that no further accesses +are made to _d_, as the memory backing it will be reclaimed for other uses. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_dialer_alloc.3str.adoc[nng_stream_dialer_alloc(3str)], +xref:nng_stream_dialer_close.3str.adoc[nng_stream_dialer_close(3str)], +xref:nng_stream_dialer_dial.3str.adoc[nng_stream_dialer_dial(3str)], +xref:nng_stream_dialer.5.adoc[nng_stream_dialer(5)] diff --git a/docs/reference/src/stream/nng_stream_dialer_get.3str.adoc b/docs/reference/src/stream/nng_stream_dialer_get.3str.adoc new file mode 100644 index 00000000..4023e56f --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer_get.3str.adoc @@ -0,0 +1,143 @@ += nng_stream_dialer_get(3str) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer_get - get option from byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_dialer_get(nng_stream_dialer *d, const char *opt, void *val, size_t *sizep); + +int nng_stream_dialer_get_bool(nng_stream_dialer *d, const char *opt, bool *valp); + +int nng_stream_dialer_get_int(nng_stream_dialer *d, const char *opt, int *valp); + +int nng_stream_dialer_get_ms(nng_stream_dialer *d, const char *opt, nng_duration *valp); + +int nng_stream_dialer_get_ptr(nng_stream_dialer *d, const char *opt, void **valp); + +int nng_stream_dialer_get_size(nng_stream_dialer *d, const char *opt, size_t *valp); + +int nng_stream_dialer_get_addr(nng_stream_dialer *d, const char *opt, nng_sockaddr *valp); + +int nng_stream_dialer_get_string(nng_stream_dialer *d, const char *opt, char **valp); + +int nng_stream_dialer_get_uint64(nng_stream_dialer *d, const char *opt, uint64_t *valp); +---- + +== DESCRIPTION + + +The `nng_stream_dialer_get()` functions are used to retrieve option values for the +xref:nng_stream_dialer.5.adoc[byte stream dialer] _d_. + +The actual options that may be retrieved in this way vary. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the connected +byte stream dialer _d_. +The forms vary based on the type of the option they take. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_stream_dialer_get()`:: +This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced by +_sizep_. ++ +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by _sizep_. +If the caller's buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in _sizep_ does not exceed the original buffer size. ++ +It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_dialer_get_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_dialer_get_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_dialer_get_ms()`:: +This function is used to retrieve time +xref:nng_duration.5.adoc[durations] +(such as timeouts), stored as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_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 underlying 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/reference/src/stream/nng_stream_dialer_set.3str.adoc b/docs/reference/src/stream/nng_stream_dialer_set.3str.adoc new file mode 100644 index 00000000..bd4ac478 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_dialer_set.3str.adoc @@ -0,0 +1,133 @@ += nng_stream_dialer_set(3str) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_dialer_set - set option on byte stream dialer + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_dialer_set(nng_stream_dialer *d, const char *name, const void *data, size_t size); + +int nng_stream_dialer_set_bool(nng_stream_dialer *d, const char *opt, bool 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_alloc.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/reference/src/stream/nng_stream_free.3str.adoc b/docs/reference/src/stream/nng_stream_free.3str.adoc new file mode 100644 index 00000000..30679458 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_free.3str.adoc @@ -0,0 +1,61 @@ += nng_stream_free(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_free - free byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_free(nng_stream *s); +---- + +== DESCRIPTION + +The `nng_stream_free()` function closes the +xref:nng_stream.5.adoc[byte stream] _s_, +and frees the underlying resources associated with it. + +If any operations are pending, such as +xref:nng_stream_send.3str.adoc[`nng_stream_send()`] +or +xref:nng_stream_recv.3str.adoc[`nng_stream_recv()`], +they will be terminated with an `NNG_ECLOSED` error condition. + +WARNING: It is important that the application ensure that no further accesses +are made to _s_, as the memory backing it will be reclaimed for other uses. + +NOTE: Closing the connection while data is in transmission will likely +lead to loss of that data. +There is no automatic linger or flush to ensure that the socket send buffers +have completely transmitted. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_close.3str.adoc[nng_stream_close(3str)], +xref:nng_stream_recv.3str.adoc[nng_stream_recv(3str)], +xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/reference/src/stream/nng_stream_get.3str.adoc b/docs/reference/src/stream/nng_stream_get.3str.adoc new file mode 100644 index 00000000..606fcc09 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_get.3str.adoc @@ -0,0 +1,146 @@ += nng_stream_get(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_get - get option from byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_get(nng_stream *s, const char *opt, void *val, size_t *sizep); + +int nng_stream_get_bool(nng_stream *s, const char *opt, bool *valp); + +int nng_stream_get_int(nng_stream *s, const char *opt, int *valp); + +int nng_stream_get_ms(nng_stream *s, const char *opt, nng_duration *valp); + +int nng_stream_get_ptr(nng_stream *s, const char *opt, void **valp); + +int nng_stream_get_size(nng_stream *s, const char *opt, size_t *valp); + +int nng_stream_get_addr(nng_stream *s, const char *opt, nng_sockaddr *valp); + +int nng_stream_get_string(nng_stream *s, const char *opt, char **valp); + +int nng_stream_get_uint64(nng_stream *s, const char *opt, uint64_t *valp); + +---- + +== DESCRIPTION + +The `nng_stream_get()` functions are used to retrieve option values for the +xref:nng_stream.5.adoc[byte stream] _conn_. + +The actual options that may be retrieved in this way vary. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the connected +byte stream _s_. +The forms vary based on the type of the option they take. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_stream_get()`:: +This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced by +_sizep_. ++ +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by _sizep_. +If the caller's buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in _sizep_ does not exceed the original buffer size. ++ +It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_get_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_get_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_get_ms()`:: +This function is used to retrieve time +xref:nng_duration.5.adoc[durations] +(such as timeouts), stored as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_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/reference/src/stream/nng_stream_listener.5.adoc b/docs/reference/src/stream/nng_stream_listener.5.adoc new file mode 100644 index 00000000..b774a1b9 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener.5.adoc @@ -0,0 +1,48 @@ += nng_stream_listener(5) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener - byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct nng_stream_listener nng_stream_listener; +---- + +== 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/reference/src/stream/nng_stream_listener_accept.3str.adoc b/docs/reference/src/stream/nng_stream_listener_accept.3str.adoc new file mode 100644 index 00000000..f5ffbca5 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_accept.3str.adoc @@ -0,0 +1,64 @@ += nng_stream_listener_accept(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_accept - accept incoming byte stream connection + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_listener_accept(nng_stream_listener *l, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_stream_listener_accept()` attempts to accept an incoming byte stream +connection from a remote peer, using the listener _l_. +The operation is completed asynchronously, using _aio_. + +This operation can only be done after the listener is already +xref:nng_stream_listener_listen.3str.adoc[listening]. + +If a connection is successfully established, the _aio_ will have the +resulting +xref:nng_stream.5.adoc[`nng_stream`] object stored as its first output, +which can be retrieved with +xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`]. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was aborted. +`NNG_ECLOSED`:: The listener is closed. +`NNG_ECONNRESET`:: The connection was reset by the peer. +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ESTATE`:: The listener is not not listening. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], +xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)], +xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)], +xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)], +xref:nng_aio.5.adoc[nng_aio(5)], +xref:nng_stream.5.adoc[nng_stream(5)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_listener_alloc.3str.adoc b/docs/reference/src/stream/nng_stream_listener_alloc.3str.adoc new file mode 100644 index 00000000..966866ba --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_alloc.3str.adoc @@ -0,0 +1,70 @@ += nng_stream_listener_alloc(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_alloc - allocate byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_listener_alloc(nng_stream_listener **lp, const char *addr); + +int nng_stream_listener_alloc_url(nng_stream_listener **lp, const nng_url *url); +---- + +== DESCRIPTION + +These functions allocates a listener for byte streams. +Listeners create +xref:nng_stream.5.adoc[`nng_stream`] objects by accepting incoming +connections, via the +xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`] +function. + +The first form, `nng_stream_listener_alloc()`, connects to the address +specified by _addr_, which should be a string representing a URL. + +The second form, `nng_stream_listener_alloc_url()`, takes a pre-parsed +or pre-constructed +xref:nng_url.5.adoc[`nng_url`] object to determine the remote address. + +These functions may support different URL schemes, such as +`ipc://`, `tcp://`, `tls+tcp://`, or `ws://`. + +Both forms store the listener in the location referenced by _lp_. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory exists. +`NNG_ENOTSUP`:: The URL scheme is not supported by the implementation. +`NNG_EADDRINVAL`:: The URL requested is invalid. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)] +xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)] +xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)] +xref:nng_stream_listener_get.3str.adoc[nng_stream_listener_get(3str)] +xref:nng_stream_listener_listen.3str.adoc[nng_stream_listener_listen(3str)] +xref:nng_stream_listener_set.3str.adoc[nng_stream_listener_set(3str)] +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_listener_close.3str.adoc b/docs/reference/src/stream/nng_stream_listener_close.3str.adoc new file mode 100644 index 00000000..a810509e --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_close.3str.adoc @@ -0,0 +1,60 @@ += nng_stream_listener_close(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_close - close byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_listener_close(nng_stream_listener *l); +---- + +== DESCRIPTION + +The `nng_stream_listener_close()` function closes the supplied connected byte +stream listener _l_, +but does not free the underlying resources associated with it. + +If any +xref:nng_stream_listener_accept.3str.adoc[accept] +operations using _d_ are +in progress, they will be terminated with an `NNG_ECLOSED` error condition. + +Furthermore any future accesses to the listener _l_ will also result in +`NNG_ECLOSED`. + +NOTE: This function does not release the memory for the listener, so the +application should still free the memory using +xref:nng_stream_listener_free.3str.adoc[`nng_stream_listener_free()`] +once it is certain that nothing else is using it. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], +xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], +xref:nng_stream_listener_free.3str.adoc[nng_stream_listener_free(3str)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_listener_free.3str.adoc b/docs/reference/src/stream/nng_stream_listener_free.3str.adoc new file mode 100644 index 00000000..aecd8895 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_free.3str.adoc @@ -0,0 +1,54 @@ += nng_stream_listener_free(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions + +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_free - free byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_listener_free(nng_stream_listener *)l; +---- + +== DESCRIPTION + +The `nng_stream_listener_free()` function closes the supplied +byte stream listener _l_, +and frees the underlying resources associated with it. + +If any +xref:nng_stream_listener_accept.3str.adoc[accept] operations using __l are +in progress, they will be terminated with an `NNG_ECLOSED` error condition. + +WARNING: It is important that the application ensure that no further accesses +are made to _l_, as the memory backing it will be reclaimed for other uses. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], +xref:nng_stream_listener_alloc.3str.adoc[nng_stream_listener_alloc(3str)], +xref:nng_stream_listener_close.3str.adoc[nng_stream_listener_close(3str)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_listener_get.3str.adoc b/docs/reference/src/stream/nng_stream_listener_get.3str.adoc new file mode 100644 index 00000000..927e36a8 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_get.3str.adoc @@ -0,0 +1,144 @@ += nng_stream_listener_get(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_get - get option from byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_listener_get(nng_stream_listener *l, const char *opt, void *val, size_t *sizep); + +int nng_stream_listener_get_bool(nng_stream_listener *l, const char *opt, bool *valp); + +int nng_stream_listener_get_int(nng_stream_listener *l, const char *opt, int *valp); + +int nng_stream_listener_get_ms(nng_stream_listener *l, const char *opt, nng_duration *valp); + +int nng_stream_listener_get_ptr(nng_stream_listener *l, const char *opt, void **valp); + +int nng_stream_listener_get_size(nng_stream_listener *l, const char *opt, size_t *valp); + +int nng_stream_listener_get_addr(nng_stream_listener *l, const char *opt, nng_sockaddr *valp); + +int nng_stream_listener_get_string(nng_stream_listener *l, const char *opt, char **valp); + +int nng_stream_listener_get_uint64(nng_stream_listener *l, const char *opt, uint64_t *valp); +---- + +== DESCRIPTION + + +The `nng_stream_listener_get()` functions are used to retrieve option values +for the +xref:nng_stream_listener.5.adoc[byte stream listener] _l_. + +The actual options that may be retrieved in this way vary. +A number of them are documented in +xref:nng_options.5.adoc[nng_options(5)] and additional linked documents. + +=== Forms + +In all of these forms, the option _opt_ is retrieved from the connected +byte stream listener _l_. +The forms vary based on the type of the option they take. + +The details of the type, size, and semantics of the option will depend +on the actual option, and will be documented with the option itself. + +`nng_stream_listener_get()`:: +This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced by +_sizep_. ++ +When the function returns, the actual size of the data copied (or that +would have been copied if sufficient space were present) is stored at +the location referenced by _sizep_. +If the caller's buffer is not large enough to hold the entire object, +then the copy is truncated. +Therefore the caller should check for truncation by verifying that the +returned size in _sizep_ does not exceed the original buffer size. ++ +It is acceptable to pass `NULL` for _val_ if the value in _sizep_ is zero. +This can be used to determine the size of the buffer needed to receive +the object. ++ +TIP: It may be easier to use one of the typed forms of this function. + +`nng_stream_listener_get_bool()`:: +This function is for options which take a Boolean (`bool`). + +`nng_stream_listener_get_int()`:: +This function is for options which take an integer (`int`). + +`nng_stream_listener_get_ms()`:: +This function is used to retrieve time +xref:nng_duration.5.adoc[durations] +(such as timeouts), stored as a number of milliseconds. +(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DURATION_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/reference/src/stream/nng_stream_listener_listen.3str.adoc b/docs/reference/src/stream/nng_stream_listener_listen.3str.adoc new file mode 100644 index 00000000..e8473b52 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_listen.3str.adoc @@ -0,0 +1,66 @@ += nng_stream_listener_listen(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_listen - bind listener to configured address + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_listener_listen(nng_stream_listener *l); +---- + +== DESCRIPTION + +The `nng_stream_listener_listen()` attempts to bind the listener _l_ +to the local address specified when the listener was created. + +This must generally be done before accepting incoming connections using +xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`]. + +For some transports this will also perform other actiosn. For example, +with TCP listeners it will configure the +underlying port into passive mode, ready to +accept an incoming connection, and established a listen queue +for receiving incoming connections. + +If binding the listener requires allocation of an address (for example +when a TCP port number of zero is specified, indicating that an +ephemeral port should be used), this operation will allocate that +resource. +This can permit retrieval of the selected address using +xref:nng_stream_listener_get.3str.adoc[`nng_stream_listener_get()`], +typically with the +xref:nng_options.5.adoc#NNG_OPT_LOCADDR[`NNG_OPT_LOCADDR`] option. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_EADDRINUSE`:: The address is already in use. +`NNG_EADDRINVAL`:: The address is invalid or unavailable. +`NNG_ECLOSED`:: The listener has been closed. +`NNG_ESTATE`:: The listener is already bound. + +== SEE ALSO + +[.text-left] +xref:nng_stream_listener_accept.3str.adoc[nng_stream_listener_accept(3str)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_listener.5.adoc[nng_stream_listener(5)] diff --git a/docs/reference/src/stream/nng_stream_listener_set.3str.adoc b/docs/reference/src/stream/nng_stream_listener_set.3str.adoc new file mode 100644 index 00000000..ccabe5ca --- /dev/null +++ b/docs/reference/src/stream/nng_stream_listener_set.3str.adoc @@ -0,0 +1,133 @@ += nng_stream_listener_set(3str) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_listener_set - set option on byte stream listener + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_listener_set(nng_stream_listener *l, const char *name, const void *data, size_t size); + +int nng_stream_listener_set_bool(nng_stream_listener *l, const char *opt, bool 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_alloc.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/reference/src/stream/nng_stream_recv.3str.adoc b/docs/reference/src/stream/nng_stream_recv.3str.adoc new file mode 100644 index 00000000..148be978 --- /dev/null +++ b/docs/reference/src/stream/nng_stream_recv.3str.adoc @@ -0,0 +1,74 @@ += nng_stream_recv(3str) +// +// Copyright 2019 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_recv - receive from byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_recv(nng_stream *s, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_stream_recv()` function starts an asynchronous receive from the +xref:nng_stream.5.adoc[byte stream] _s_ +into the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The +xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. +Completion of the operation is signaled via the _aio_, +and the final result may be obtained via +xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +The I/O operation completes as soon as at least one byte has been +received, or an error has occurred. +Therefore, the number of bytes read may be less than requested. +The actual number of bytes read can be determined with +xref:nng_aio_count.3.adoc[`nng_aio_count()`]. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ECONNSHUT`:: Remote peer shutdown after sending data. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_close.3str.adoc[nng_stream_close(3str)], +xref:nng_stream_send.3str.adoc[nng_stream_send(3str)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/reference/src/stream/nng_stream_send.3str.adoc b/docs/reference/src/stream/nng_stream_send.3str.adoc new file mode 100644 index 00000000..5a53e63c --- /dev/null +++ b/docs/reference/src/stream/nng_stream_send.3str.adoc @@ -0,0 +1,74 @@ += nng_stream_send(3str) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_send - send to byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +void nng_stream_send(nng_stream *s, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_stream_send()` function starts an asynchronous send over the +xref:nng_stream.5.adoc[byte stream] _s_ +from the scatter/gather vector located in the +asynchronous I/O structure _aio_. + +NOTE: The +xref:nng_aio_set_iov.3.adoc[`nng_aio_set_iov()`] +function must have been +called first, to set the scatter/gather vector for _aio_. + +This function returns immediately, with no return value. +Completion of the operation is signaled via the _aio_, and the final +result may be obtained via +xref:nng_aio_result.3.adoc[`nng_aio_result()`]. +That result will either be zero or an error code. + +The I/O operation completes as soon as at least one byte has been +sent, or an error has occurred. +Therefore, the number of bytes sent may be less than requested. +The actual number of bytes sent can be determined with +xref:nng_aio_count.3.adoc[`nng_aio_count()`]. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_EINVAL`:: The _aio_ does not contain a valid scatter/gather vector. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)], +xref:nng_aio_count.3.adoc[nng_aio_count(3)], +xref:nng_aio_result.3.adoc[nng_aio_result(3)], +xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)], +xref:nng_strerror.3.adoc[nng_strerror(3)], +xref:nng_stream_close.3str.adoc[nng_stream_close(3str)], +xref:nng_stream_recv.3str.adoc[nng_stream_recv(3str)], +xref:nng_stream.5.adoc[nng_stream(5)] diff --git a/docs/reference/src/stream/nng_stream_set.3str.adoc b/docs/reference/src/stream/nng_stream_set.3str.adoc new file mode 100644 index 00000000..e4a82a1a --- /dev/null +++ b/docs/reference/src/stream/nng_stream_set.3str.adoc @@ -0,0 +1,133 @@ += nng_stream_set(3str) +// +// Copyright 2020 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2019 Devolutions +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_stream_set - set option on byte stream + +== SYNOPSIS + +[source, c] +---- +#include + +int nng_stream_set(nng_stream *s, const char *name, const void *data, size_t size); + +int nng_stream_set_bool(nng_stream *s, const char *opt, bool 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_alloc.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/reference/src/tran/ipc.md b/docs/reference/src/tran/ipc.md new file mode 100644 index 00000000..b2daa40e --- /dev/null +++ b/docs/reference/src/tran/ipc.md @@ -0,0 +1,95 @@ +# IPC Transport + +## DESCRIPTION + +The {{i:*ipc* transport}}{{hi:*ipc*}} provides communication support between +sockets within different processes on the same host. +For POSIX platforms, this is implemented using {{i:UNIX domain sockets}}. +For Windows, this is implemented using Windows {{i:named pipes}}. +Other platforms may have different implementation strategies. + +### URI Formats + +#### Traditional Names + +This transport uses URIs using the scheme {{i:`ipc://`}}, followed by a path +name in the file system where the socket or named pipe should be created. + +> [!TIP] +> On Windows, all names are prefixed by `\\.\pipe\` and do not +> reside in the normal file system. +> On POSIX platforms, the path is taken literally, and is relative to +> the current directory, unless it begins with `/`, in which case it is +> relative to the root directory. + +> [!NOTE] +> When using relative paths on POSIX systems, the address used and returned +> in properties like `NNG_OPT_LOCADDR` and `NNG_OPT_URL` will also be relative. +> Consequently, they will only be interpreted the same by processes that have +> the same working directory. +> To ensure maximum portability and safety, absolute paths are recommended +> whenever possible. + +> [!NOTE] +> If compatibility with legacy _nanomsg_ applications is required, +> then path names must not be longer than 122 bytes, including the final +> `NUL` byte. +> This is because legacy versions of _nanomsg_ cannot express URLs +> longer than 128 bytes, including the `ipc://` prefix. + +#### UNIX Aliases + +The {{i:`unix://`}} scheme is an alias for `ipc://` and can be used inter-changeably, but only on POSIX systems.[^1] + +[^1]: + The purpose of this scheme is to support a future transport making use of {{i:`AF_UNIX`}} + on Windows systems, at which time it will be necessary to discriminate between + the Named Pipes and the `AF_UNIX` based transports. + +#### Abstract Names + +On Linux, this transport also can support {{i:abstract sockets}}. +Abstract sockets use a URI-encoded name after the {{i:`abstract://`}} scheme, which allows arbitrary values to be conveyed +in the path, including embedded `NUL` bytes. +For example, the name `"a\0b"` would be represented as `abstract://a%00b`. + +> [!TIP] +> An empty name may be used with a listener to request "auto bind" be used to select a name. +> In this case the system will allocate a free name. +> The name assigned may be retrieved using [{{i:`NNG_OPT_LOCADDR`}}][NNG_OPT_LOCADDR]. + +Abstract names do not include the leading `NUL` byte used in the low-level socket address. + +Abstract sockets do not have any representation in the file system, and are automatically freed by +the system when no longer in use. + +Abstract sockets ignore socket permissions, but it is still possible to determine the credentials +of the peer with [{{i:`NNG_OPT_PEER_UID`}}][NNG_OPT_PEER_UID], and similar options.[^2] + +[^2]: + This property makes it important that names be chosen randomly to + prevent unauthorized access, or that checks against the peer credentials + are made, or ideally, both. + +### Socket Address + +When using an [`nng_sockaddr`][sockaddr] structure, +the actual structure is of type [`nng_sockaddr_ipc`][sockaddr_ipc], +except for abstract sockets, which use [`nng_sockaddr_abstract`][sockaddr_abstract]. + +### Transport Options + +The following transport options are supported by this transport, +where supported by the underlying platform. + +- [`NNG_OPT_IPC_PERMISSIONS`][NNG_OPT_IPC_PERMISSIONS] +- [`NNG_OPT_IPC_SECURITY_DESCRIPTOR`][NNG_OPT_IPC_SECURITY_DESCRIPTOR] +- [`NNG_OPT_LOCADDR`][NNG_OPT_LOCADDR] +- [`NNG_OPT_REMADDR`][NNG_OPT_REMADDR] +- [`NNG_OPT_PEER_GID`][NNG_OPT_PEER_GID] +- [`NNG_OPT_PEER_PID`][NNG_OPT_PEER_PID] +- [`NNG_OPT_PEER_UID`][NNG_OPT_PEER_UID] +- [`NNG_OPT_PEER_ZONEID`][NNG_OPT_PEER_ZONEID] +- [`NNG_OPT_URL`][NNG_OPT_URL] + +{{#include ../refs.md}} -- cgit v1.2.3-70-g09d2