diff options
Diffstat (limited to 'docs')
25 files changed, 0 insertions, 2009 deletions
diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index 6db3318f..8d48c78f 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -199,31 +199,6 @@ if (NNG_ENABLE_DOC) nng_zt_register ) - set(NNG_MAN3COMPAT - nn_allocmsg - nn_bind - nn_close - nn_cmsg - nn_connect - nn_device - nn_errno - nn_freemsg - nn_get_statistic - nn_getsockopt - nn_poll - nn_reallocmsg - nn_recv - nn_recvmsg - nn_send - nn_sendmsg - nn_setsockopt - nn_shutdown - nn_socket - nn_strerror - nn_term - nng_compat - ) - set(NNG_MAN3HTTP nng_http_client_alloc nng_http_client_connect @@ -414,10 +389,6 @@ if (NNG_ENABLE_DOC) nng_man(${F} 3) endforeach () - foreach (F ${NNG_MAN3COMPAT}) - nng_man(${F} 3compat) - endforeach () - foreach (F ${NNG_MAN3HTTP}) nng_man(${F} 3http) endforeach () diff --git a/docs/man/man3compat.desc b/docs/man/man3compat.desc deleted file mode 100644 index 2b0b4b3f..00000000 --- a/docs/man/man3compat.desc +++ /dev/null @@ -1,13 +0,0 @@ -This section documents the _nanomsg_ 1.0 libary compatible functions. - -These functions are provided as a transition aid, for application -developers coming to _NNG_ from _libnanomsg_, and are discouraged -from use in new applications. - -TIP: While this is discouraged for long term use, as a transition aid -applications may use the value returned by the -xref:nng_socket_id.3.adoc[`nng_socket_id()`] in these functions just like a -socket descriptor (as if the socket were opened via -xref:nn_socket.3compat.adoc[`nn_socket()`]). -This sort of API intermixing should only be used during transition from -the legacy API to the new API. diff --git a/docs/man/man3compat.sect b/docs/man/man3compat.sect deleted file mode 100644 index 75a97a08..00000000 --- a/docs/man/man3compat.sect +++ /dev/null @@ -1 +0,0 @@ -Compatible Library Functions diff --git a/docs/man/nn_allocmsg.3compat.adoc b/docs/man/nn_allocmsg.3compat.adoc deleted file mode 100644 index a53da55c..00000000 --- a/docs/man/nn_allocmsg.3compat.adoc +++ /dev/null @@ -1,67 +0,0 @@ -= nn_allocmsg(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_allocmsg - allocate message (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -void *nn_allocmsg(size_t size, int type); ----- - -== DESCRIPTION - -The `nn_allocmsg()` allocates a message structure of size _size_, and is -primarily used to support zero-copy send operations, making use of the -`NNG_MSG` special size indicator. -The value returned is a pointer to the start of the message payload buffer. - -The value of _size_ must be positive, and small enough to hold reasonable -message data plus book-keeping information. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The value of _type_ *must* be zero. -(This argument was reserved to support different kinds of memory spaces -for RDMA devices, but this was never developed in the legacy API.) - -The returned message must be disposed of by either -xref:nn_freemsg.3compat.adoc[`nn_freemsg()`] or -xref:nn_send.3compat.adoc[`nn_send()`] when the caller is finished with it. - -== RETURN VALUES - -This function returns a pointer to message buffer space, or `NULL` -on failure. - -== ERRORS - -[horizontal] -`ENOMEM`:: Insufficient memory is available. -`EINVAL`:: An invalid _size_ or _type_ was specified. -`ETERM`:: The library is shutting down. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_freemsg.3compat.adoc[nn_freemsg(3compat)], -xref:nn_reallocmsg.3compat.adoc[nn_reallocmsg(3compat)], -xref:nn_send.3compat.adoc[nn_send(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_bind.3compat.adoc b/docs/man/nn_bind.3compat.adoc deleted file mode 100644 index a4ca0043..00000000 --- a/docs/man/nn_bind.3compat.adoc +++ /dev/null @@ -1,68 +0,0 @@ -= nn_bind(3compat) -// -// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_bind - accept connections from remote peers (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include <nanomsg/nn.h> - -int nn_bind(int sock, const char *url) ----- - -== DESCRIPTION - -The `nn_bind()` function arranges for the socket _sock_ to -accept connections at the address specified by _url_. -An identifier for this socket's association with the _url_ is -returned to the caller on success. -This identfier can be used with -xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to -remove the association later. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -NOTE: The bind operation is performed asynchronously, and may not have -completed before this function returns control to the caller. - -IMPORTANT: Only transports supported by legacy _libnanomsg_ may be -used with this function. -In particular, only the schemes `tcp://`, `ipc://`, `inproc://`, and `ws://` are -supported with this function. -(Use the xref:libnng.3.adoc[modern API] to use other schemes.) - -== RETURN VALUES - -This function returns a positive identifier on success, and -1 on error. - -== ERRORS - -[horizontal] -`EADDRINUSE`:: The address specified by _url_ is already in use. -`EADDRNOTAVAIL`:: The address specified by _url_ is not available. -`EBADF`:: The socket _sock_ is not open. -`EINVAL`:: An invalid _url_ was supplied. - -== SEE ALSO - -[.text-left] -xref:nn_connect.3compat.adoc[nn_connect(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_shutdown.3compat.adoc[nn_shutdown(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_close.3compat.adoc b/docs/man/nn_close.3compat.adoc deleted file mode 100644 index 1970b57d..00000000 --- a/docs/man/nn_close.3compat.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= nn_close(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_close - close socket (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -int nn_close(int sock); ----- - -== DESCRIPTION - -The `nn_close()` function closes the socket _sock_. -Any operations that are currently in progress will be terminated, and will -fail with error `EBADF`. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -== RETURN VALUES - -This function returns zero on success, and -1 on failure. - -== ERRORS - -[horizontal] -`EBADF`:: The socket is not open. -`ETERM`:: The library is shutting down. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_cmsg.3compat.adoc b/docs/man/nn_cmsg.3compat.adoc deleted file mode 100644 index 32d31810..00000000 --- a/docs/man/nn_cmsg.3compat.adoc +++ /dev/null @@ -1,78 +0,0 @@ -= nn_cmsg(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_cmsg - message control data (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -struct nn_cmsghdr { - size_t cmsg_len; - int cmsg_level; - int cmsg_type; -}; ----- - -== DESCRIPTION - -The `nn_cmsghdr` structure describes a block of control data that is -associated with a message either sent by xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`] -or received by xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]. - -NOTE: This structure and supporting macros are provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -Each header is followed by `cmsg_len` bytes of data, plus any padding required -to align the structure. - -The only defined ancillary data at this time is the protocol headers used by -the protocols. -This uses `cmsg_level` set to `PROTO_SP` and the `cmsg_type` set to -`SP_HDR`. -The actual data for this will vary from depending on the protocol used. - -Convenience macros are provided to make working with these fields easier. - -`struct nn_cmsghdr *NN_CMSG_FIRSTHDR(struct nn_msghdr *__hdr__)`:: -This macro returns the first `struct nn_cmsghdr` header in _hdr_. - -`struct nn_cmsghdr *NN_CMSG_NXTHDR(struct nn_msghdr *__hdr__, struct nn_cmsghdr *__ch__)`:: -This macro returns a pointer to the next `struct nn_cmsghdr` in _hdr_ after _ch_. - -`void *NN_CMSG_DATA(struct nn_cmsghdr *__ch__)`:: -This macro returns a pointer to the header-specific data for _ch_. - -`size_t NN_CMSG_ALIGN(size_t __len__)`:: -This macro returns the length specified by _len_, plus any padding required to -provide the necessary alignment for another structure. - -`size_t NN_CMSG_SPACE(size_t __len__)`:: -This macro returns the amount of space required for a header, with _len_ -bytes of following data, and any necessary padding. - -`size_t NN_CMSG_LEN(size_t __len__)`:: -This macro evaluates to the length of the header (including alignment), -and the associated data of length _len_, but without any trailing padding -to align for another header. - -== SEE ALSO - -[.text-left] -xref:nn_recvmsg.3compat.adoc[nn_recvmsg(3compat)], -xref:nn_sendmsg.3compat.adoc[nn_sendmsg(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_connect.3compat.adoc b/docs/man/nn_connect.3compat.adoc deleted file mode 100644 index e498f8d3..00000000 --- a/docs/man/nn_connect.3compat.adoc +++ /dev/null @@ -1,67 +0,0 @@ -= nn_connect(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_connect - connect to remote peer (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include <nanomsg/nn.h> - -int nn_connect(int sock, const char *url) ----- - -== DESCRIPTION - -The `nn_connect()` function arranges for the socket _sock_ to -initiate connection to a peer at the address specified by _url_. -An identifier for this socket's association with the _url_ is -returned to the caller on success. -This identifier can be used with -xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to -remove the association later. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -NOTE: The connect operation is performed asynchronously, and may not have -completed before this function returns control to the caller. - -IMPORTANT: Only transports supported by legacy _libnanomsg_ may be -used with this function. -In particular, only the schemes `tcp://`, `ipc://`, `inproc://`, and `ws://` are -supported with this function. -(Use the xref:libnng.3.adoc[modern API] to use other schemes.) - -== RETURN VALUES - -This function returns a positive identifier success, and -1 on error. - -== ERRORS - -[horizontal] -`ECONNREFUSED`:: The connection attempt was refused. -`EBADF`:: The socket _sock_ is not open. -`EINVAL`:: An invalid _url_ was supplied. - -== SEE ALSO - -[.text-left] -xref:nn_bind.3compat.adoc[nn_bind(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_shutdown.3compat.adoc[nn_shutdown(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_device.3compat.adoc b/docs/man/nn_device.3compat.adoc deleted file mode 100644 index c69e1e04..00000000 --- a/docs/man/nn_device.3compat.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nn_device(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_device - create forwarding device (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -int nn_device(int sock1, int sock2); ----- - -== DESCRIPTION - -The `nn_device()` function is used to create a forwarder, where messages -received on one of the two sockets _sock1_ and _sock2_ are forwarded to -the other. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The two sockets must be compatible, and must be -xref:nng.7.adoc#raw_mode[raw mode] -sockets. -More detail about devices and how they can be used is available in the -new style xref:nng_device.3.adoc[nng_device()] documentation. - -== RETURN VALUES - -This function blocks forever, and will return -1 only when -one of the sockets is closed or an error occurs. - -== ERRORS - -[horizontal] -`EBADF`:: One of the two sockets is invalid or not open, or has -`EINVAL`:: The sockets are not compatible with each other, or not both raw. -`ENOMEM`:: Insufficient memory is available. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_errno.3compat.adoc b/docs/man/nn_errno.3compat.adoc deleted file mode 100644 index a048543d..00000000 --- a/docs/man/nn_errno.3compat.adoc +++ /dev/null @@ -1,79 +0,0 @@ -= nn_errno(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_errno - return most recent error (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -int nn_errno(void); ----- - -== DESCRIPTION - -The `nn_errno()` function returns the error number corresponding to the -most recent failed operation by the calling thread. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -IMPORTANT: The error numbers returned from this function may include -errors caused by system functions, which overlap the usual `errno` variable, -and this function simply returns the value of `errno`. -However, the values returned may include numeric values that are not -defined by the system, but are unique to _libnanomsg_, such as `EFSM`. - -This library implements the following error numbers, in addition to any others -that might be set for `errno` by the underlying system: - - -== RETURN VALUES - -This function returns the value of `errno`. -If no operation has failed, then this will be zero. - -== ERRORS - -[horizontal] -`EINTR`:: Operation interrupted. -`ENOMEM`:: Insufficient memory. -`EINVAL`:: Invalid argument. -`EBUSY`:: Resource is busy. -`ETIMEDOUT`:: Operation timed out. -`ECONNREFUSED`:: Connection refused by peer. -`EBADF`:: Invalid or closed socket. -`EAGAIN`:: Operation would block. -`ENOTSUP`:: Protocol or option not supported. -`EADDRINUSE`:: Requested address is already in use. -`EFSM`:: Protocol state incorrect. -`EPROTO`:: Protocol error. -`EHOSTUNREACH`:: Remote peer is unreachable. -`EADDRNOTAVAIL`:: Requested address is not available. -`EACCES`:: Permission denied. -`EMSGSIZE`:: Message is too large. -`ECONNABORTED`:: Connection attempt aborted. -`ECONNRESET`:: Connection reset by peer. -`EEXIST`:: Resource already exists. -`EMFILE`:: Too many open files. -`ENOSPC`:: Insufficient persistent storage. - -== SEE ALSO - -[.text-left] -xref:nn_strerror.3compat.adoc[nn_strerror(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_freemsg.3compat.adoc b/docs/man/nn_freemsg.3compat.adoc deleted file mode 100644 index 61127c3d..00000000 --- a/docs/man/nn_freemsg.3compat.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= nn_freemsg(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_freemsg - free message (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -int nn_freemsg(void *msg); ----- - -== DESCRIPTION - -The `nn_freemsg()` deallocates a message previously allocated with -xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`] or similar functions. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -== RETURN VALUES - -This function always returns 0. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nn_allocmsg.3compat.adoc[nn_allocmsg(3compat)], -xref:nn_freemsg.3compat.adoc[nn_freemsg(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_get_statistic.3compat.adoc b/docs/man/nn_get_statistic.3compat.adoc deleted file mode 100644 index 89b11de2..00000000 --- a/docs/man/nn_get_statistic.3compat.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= nn_get_statistic(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_get_statistic - get statistic (stub) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -uint64_t nn_get_statistic(int sock, int stat); ----- - -== DESCRIPTION - -The `nn_get_statistic()` function exists only as a stub, and always returns -zero. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -== RETURN VALUES - -Zero. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_getsockopt.3compat.adoc b/docs/man/nn_getsockopt.3compat.adoc deleted file mode 100644 index 0c476cca..00000000 --- a/docs/man/nn_getsockopt.3compat.adoc +++ /dev/null @@ -1,228 +0,0 @@ -= nn_getsockopt(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_getsockopt - get socket option (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -int nn_getsockopt(int sock, int level, int option, void *val, size_t *szp); ----- - -== DESCRIPTION - -The `nn_getsockopt()` function gets a socket option on socket _sock_. -The option retrieved is determined by the _level_ and _option_. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The value pointed to by _szp_ must be initialized to the size of the buffer -pointed to by _val_. -No more than this many bytes of the option will be copied into the destination -buffer on success. -On success, the value pointed to by _szp_ will be updated with the actual -size of the option. - -TIP: To determine the size to receive an option, first call this function -with _val_ set to `NULL` and the value addressed by _szp_ initialized to zero. - -The _level_ determines whether the option is a generic socket option, -or is transport-specific. -The values possible for level are as follows: - -[horizontal] -`NN_SOL_SOCKET`:: Generic socket option -`NN_IPC`:: Transport specific option for IPC. -`NN_TCP`:: Transport specific option for TCP. -`NN_WS`:: Transport specific option for WebSocket. - -The following generic socket options are possible (all are of type `int` and -thus size 4, unless otherwise indicated.) - -`NN_SNDBUF`:: -Send buffer size in bytes. - -NOTE: In _NNG_ buffers are sized as a count of messages rather than -bytes; accordingly this value is the queue depth multiplied by 1024 -(representing an estimate that the average message size is 1kB). -Applications that have unusual message sizes may wish to adjust the value -used here accordingly. - -`NN_RCVBUF`:: -Receive buffer size in bytes. - -NOTE: The same caveats for `NN_SNDBUF` apply here as well. - -`NN_SNDTIMEO`:: -Send time-out in milliseconds. -Send operations will fail with `ETIMEDOUT` if no message can be received -after this many milliseconds have transpired since the operation was started. -A value of -1 means that no timeout is applied. - -`NN_RCVTIMEO`:: -Receive time-out in milliseconds. -Receive operations will fail with `ETIMEDOUT` if no message can be received -after this many milliseconds have transpired since the operation was started. -A value of -1 means that no timeout is applied. - -`NN_RCVMAXSIZE`:: -Maximum receive size in bytes. -The socket will discard messages larger than this on receive. -The default, 1MB, is intended to prevent denial-of-service attacks. -The value -1 removes any limit. - -`NN_RECONNECT_IVL`:: -Reconnect interval in milliseconds. -After an outgoing connection is closed or fails, the socket will -automatically attempt to reconnect after this many milliseconds. -This is the starting value for the time, and is used in the first -reconnection attempt after a successful connection is made. -The default is 100. - -`NN_RECONNECT_IVL_MAX`:: -Maximum reconnect interval in milliseconds. -Subsequent reconnection attempts after a failed attempt are made at -exponentially increasing intervals (back-off), but the interval is -capped by this value. -If this value is smaller than `NN_RECONNECT_IVL`, then no exponential -back-off is performed, and each reconnect interval will be determined -solely by `NN_RECONNECT_IVL`. -The default is zero. - -`NN_LINGER`:: -This option is always zero and exists only for compatibility. - -NOTE: This option was unreliable in early releases of _libnanomsg_, and -is unsupported in _NNG_ and recent _libnanomsg_ releases. -Applications needing assurance of message delivery should either include an -explicit notification (automatic with the `NN_REQ` protocol) or allow -sufficient time for the socket to drain before closing the socket or exiting. - - -`NN_SNDPRIO`:: -This option is not implemented at this time. - -`NN_RCVPRIO`:: -This option is not implemented at this time. - -`NN_IPV4ONLY`:: -This option is not implemented at this time. - -`NN_SOCKET_NAME`:: -This option is a string, and represents the socket name. -It can be changed to help with identifying different sockets with -their different application-specific purposes. - -`NN_MAXTTL`:: -Maximum number of times a message may traverse devices or proxies. -This value, if positive, provides some protection against forwarding loops in -xref:nng_device.3.adoc[device] chains. - -NOTE: Not all protocols offer this protection, so care should still be used -in configuring device forwarding. - -`NN_DOMAIN`:: -This option of type `int` represents either the value `AF_SP` or `AF_SP_RAW`, -corresponding to the value that the socket was created with. - -`NN_PROTOCOL`:: -This option option of type `int` contains the numeric protocol number -that the socket is used with. - -`NN_RCVFD`:: -This option returns a file descriptor suitable for use in with `poll()` or -`select()` (or other system-specific polling functions). -This descriptor will be readable when a message is available for receiving -at the socket. -This option is of type `int` on all systems except Windows, where it is of -type `SOCKET`. - -NOTE: The file descriptor should not be read or written by the application, -and is not the same as any underlying descriptor used for network sockets. - -`NN_SNDFD`:: -This option returns a file descriptor suitable for use in with `poll()` or -`select()` (or other system-specific polling functions). -This descriptor will be readable when the socket is able to accept a message -for sending. -This option is of type `int` on all systems except Windows, where it is of -type `SOCKET`. - -NOTE: The file descriptor should not be read or written by the application, -and is not the same as any underlying descriptor used for network sockets. -Furthermore, the file descriptor should only be polled for _readability_. - -The following option is available for `NN_REQ` sockets -using the `NN_REQ` level: - -`NN_REQ_RESEND_IVL`:: -Request retry interval in milliseconds. -If an `NN_REQ` socket does not receive a reply to a request within this -period of time, the socket will automatically resend the request. -The default value is 60000 (one minute). - -The following option is available for `NN_SURVEYOR` sockets -using the `NN_SURVEYOR` level: - -`NN_SURVEYOR_DEADLINE`:: -Survey deadline in milliseconds for `NN_SURVEYOR` sockets. -After sending a survey message, the socket will only accept responses -from respondents for this long. -Any responses arriving after this expires are silently discarded. - -In addition, the following transport specific options are offered: - -`NN_IPC_SEC_ATTR`:: -This `NN_IPC` option is not supported at this time. - -`NN_IPC_OUTBUFSZ`:: -This `NN_IPC` option is not supported at this time. - -`NN_IPC_INBUFSZE`:: -This `NN_IPC` option is not supported at this time. - -`NN_TCP_NODELAY`:: -This `NN_TCP` option is not supported at this time. - -`NN_WS_MSG_TYPE`:: -This `NN_WS` option is not supported, as _NNG_ only supports binary messages -in this implementation. - -== RETURN VALUES - -This function returns zero on success, and -1 on failure. - -== ERRORS - -[horizontal] -`EBADF`:: The socket _sock_ is not an open socket. -`ENOMEM`:: Insufficient memory is available. -`ENOPROTOOPT`:: The level and/or option is invalid. -`EINVAL`:: The option, or the value passed, is invalid. -`ETERM`:: The library is shutting down. -`EACCES`:: The option cannot be changed. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nn_close.3compat.adoc[nn_close(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_getsockopt.3compat.adoc[nn_getsockopt(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_poll.3compat.adoc b/docs/man/nn_poll.3compat.adoc deleted file mode 100644 index c115fe49..00000000 --- a/docs/man/nn_poll.3compat.adoc +++ /dev/null @@ -1,102 +0,0 @@ -= nn_poll(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_poll - poll sockets (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include <nanomsg/nn.h> - -#define NN_POLLIN 1 -#define NN_POLLOUT 2 - -struct nn_pollfd { - int fd; - uint16_t events; - uint16_t revents; -}; - -int nn_poll(struct nn_pollfd *pfds, int npfd, int timeout); ----- - -== DESCRIPTION - -The `nn_poll()` function polls a group of sockets for readiness to send or receive. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The array of _nfds_ sockets to poll for are passed into _pfds_. -Each member of this array is initialized with the `fd` field set to -the socket, and the `events` field set to a mask that can contain either or both -of the flags `NN_POLLIN` and `NN_POLLOUT`. - -The flag `NN_POLLIN` indicates that a socket is ready for receiving without -blocking (a message is available on the socket), and the flag `NN_POLLOUT` -indicates that a socket is ready for sending without blocking. - -Upon success, the function returns the number of updates the `revents` -field of each member of the _pfds_ array, setting it to indicate -whether the requested status is true or not. - -NOTE: The `revents` field will only have a flag set if the corresponding -flag was also set in the `events` field. - -If the _timeout_ field is positive, then this function will wait for -up the that many milliseconds. -If none of the requested events occurs before that timeout occurs, then -the function will return -1 and set the error to `ETIMEDOUT`. - -If the _timeout_ is zero, then this function will return immediately, -after updating the current status of the sockets. - -If the _timeout_ is -1, then the function waits forever, or until one of the -requested events occurs. - -IMPORTANT: This function is only suitable for use with sockets obtained with the -xref:nn_socket.3compat.adoc[`nn_socket()`] function, and is not compatible -with file descriptors obtained via any other means. -This includes file descriptors obtained using the `NN_SNDFD` or `NN_RCVFD` -options with xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`] - -NOTE: This function is significantly less efficient than other polling -or asynchronous I/O mechanisms, and is provided for API compatibility only. -It's use is discouraged. - -NOTE: This function is *not* supported on systems other than POSIX derived -platforms and Windows. - -== RETURN VALUES - -This function returns the number of sockets with events on success, or -1 on error. - -== ERRORS - -[horizontal] -`ENOMEM`:: Insufficient memory available. -`EBADF`:: One of the sockets is not open. -`ETIMEDOUT`:: Operation timed out. -`ENOTSUP`:: This function is not supported on this platform. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_recv.3compat.adoc[nn_recv(3compat)], -xref:nn_send.3compat.adoc[nn_send(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_reallocmsg.3compat.adoc b/docs/man/nn_reallocmsg.3compat.adoc deleted file mode 100644 index d48b5d40..00000000 --- a/docs/man/nn_reallocmsg.3compat.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nn_reallocmsg(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_reallocmsg - reallocate message (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -void *nn_reallocmsg(void *old, size_t size); ----- - -== DESCRIPTION - -The `nn_reallocmsg()` reallocates the message _old_, making it of size _size_. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -On success, the contents of _old_ are copied into the new message -(truncating if appropriate), then _old_ is deallocated, and a pointer -to the new message payload is returned. - -On failure, the _old_ message is unchanged, and the value `NULL` is returned -to the caller. - -== RETURN VALUES - -This function returns a pointer to message buffer space, or `NULL` -on failure. - -== ERRORS - -[horizontal] -`ENOMEM`:: Insufficient memory is available. -`EINVAL`:: An invalid _size_ was specified. -`ETERM`:: The library is shutting down. - -== SEE ALSO - -[.text-left] -xref:nn_allocmsg.3compat.adoc[nn_allocmsg(3compat)], -xref:nn_freemsg.3compat.adoc[nn_freemsg(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_recv.3compat.adoc b/docs/man/nn_recv.3compat.adoc deleted file mode 100644 index 2a71714d..00000000 --- a/docs/man/nn_recv.3compat.adoc +++ /dev/null @@ -1,75 +0,0 @@ -= nn_recv(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_recv - receive data (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include <nanomsg/nn.h> - -int nn_recv(int sock, void *data, size_t size, int flags) ----- - -== DESCRIPTION - -The `nn_recv()` function receives a message from the socket _sock_. -The message body must fit within _size_ bytes, and will be stored -at the location specified by _data_, unless _size_ is the -special value `NN_MSG`, indicating a zero-copy operation. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -If _size_ has the special value `NN_MSG`, then a zero-copy operation -is performed. -In this case, instead of copying the message data into the address -specified by _data_, a new message large enough to hold the message data -will be allocated (as if by the -function xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]), and the message -payload will be stored accordingly. -In this case, the value stored at _data_ will not be message data, -but a pointer to the message itself. -In this case, on success, the caller shall take responsibility for -the final disposition of the message (such as by sending it to -another peer using xref:nn_send.3compat.adoc[`nn_send()`]) or -xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]. - -The _flags_ field may contain the special flag `NN_DONTWAIT`. -In this case, if the no message is available for immediate receipt, -the operation shall not block, but instead will fail with the error `EAGAIN`. - -== RETURN VALUES - -This function returns the number of bytes sent on success, and -1 on error. - -== ERRORS - -[horizontal] -`EAGAIN`:: The operation would block. -`EBADF`:: The socket _sock_ is not open. -`EFSM`:: The socket cannot receive in this state. -`ENOTSUP`:: This protocol cannot receive. -`ETIMEDOUT`:: Operation timed out. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_recvmsg.3compat.adoc[nn_recvmsg(3compat)], -xref:nn_send.3compat.adoc[nn_send(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_recvmsg.3compat.adoc b/docs/man/nn_recvmsg.3compat.adoc deleted file mode 100644 index e0fcc758..00000000 --- a/docs/man/nn_recvmsg.3compat.adoc +++ /dev/null @@ -1,99 +0,0 @@ -= nn_recvmsg(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_recvmsg - receive message (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include <nanomsg/nn.h> - -int nn_recvmsg(int sock, struct nn_msghdr *hdr, int flags); ----- - -== DESCRIPTION - -The `nn_recvmsg()` function receives a message into the header described by -_hdr_ using the socket _sock_. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The _flags_ field may contain the special flag `NN_DONTWAIT`. -In this case, if no message is ready for receiving on _sock_, -the operation shall not block, but instead will fail with the error `EAGAIN`. - -The _hdr_ points to a structure of type `struct nn_msghdr`, which has the -following definition: - -[source, c] ----- -struct nn_iovec { - void * iov_base; - size_t iov_len; -}; - -struct nn_msghdr { - struct nn_iovec *msg_iov; - int msg_iovlen; - void * msg_control; - size_t msg_controllen; -}; ----- - -The `msg_iov` is an array of scatter items, permitting the message -to be spread into different memory blocks. -There are `msg_iovlen` elements in this array, each of which -has the base address (`iov_base`) and length (`iov_len`) indicated. - -The last member of this array may have the `iov_len` field set to `NN_MSG`, -in which case the function shall allocate a message buffer, and store the -pointer to it at the address indicated by `iov_base`. -This can help save an extra copy operation. -The buffer should be deallocated by xref:nn_freemsg.3compat.adoc[`nn_freemsg()`] -or similar when it is no longer needed. - -The values of `msg_control` and `msg_controllen` describe a buffer -of ancillary data associated with the message. -This is currently only useful to obtain the message headers -used with xref:nng.7.adoc#raw_mode[raw mode] sockets. -In all other circumstances these fields should be zero. -Details about this structure are covered in -xref:nn_cmsg.3compat.adoc[`nn_cmsg(3compat)`]. - -== RETURN VALUES - -This function returns the number of bytes received on success, and -1 on error. - -== ERRORS - -[horizontal] -`EAGAIN`:: The operation would block. -`EBADF`:: The socket _sock_ is not open. -`EFSM`:: The socket cannot receive in this state. -`EINVAL`:: The _hdr_ is invalid. -`ENOTSUP`:: This protocol cannot receive. -`ETIMEDOUT`:: Operation timed out. - -== SEE ALSO - -[.text-left] -xref:nn_cmsg.3compat.adoc[nn_cmsg(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_recv.3compat.adoc[nn_recv(3compat)], -xref:nn_send.3compat.adoc[nn_send(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_send.3compat.adoc b/docs/man/nn_send.3compat.adoc deleted file mode 100644 index 050bea17..00000000 --- a/docs/man/nn_send.3compat.adoc +++ /dev/null @@ -1,74 +0,0 @@ -= nn_send(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_send - send data (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include <nanomsg/nn.h> - -int nn_send(int sock, const void *data, size_t size, int flags) ----- - -== DESCRIPTION - -The `nn_send()` function creates a message containing _data_ (of size _size_), -and sends using the socket _sock_. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -If _size_ has the special value `NN_MSG`, then a zero-copy operation -is performed. -In this case, _data_ points not to the message content itself, but instead -is a pointer to the pointer, an extra level of pointer indirection. -The message must have been previously allocated by -xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`] or -xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]`, using the same `NN_MSG` size. -In this case, the ownership of the message shall remain with -the caller, unless the function returns 0, indicating that the -function has taken responsibility for delivering or disposing of the -message. - -The _flags_ field may contain the special flag `NN_DONTWAIT`. -In this case, if the socket is unable to accept more data for sending, -the operation shall not block, but instead will fail with the error `EAGAIN`. - -NOTE: The send operation is performed asynchronously, and may not have -completed before this function returns control to the caller. - -== RETURN VALUES - -This function returns the number of bytes sent on success, and -1 on error. - -== ERRORS - -[horizontal] -`EAGAIN`:: The operation would block. -`EBADF`:: The socket _sock_ is not open. -`EFSM`:: The socket cannot send in this state. -`ENOTSUP`:: This protocol cannot send. -`ETIMEDOUT`:: Operation timed out. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_recv.3compat.adoc[nn_recv(3compat)], -xref:nn_sendmsg.3compat.adoc[nn_sendmsg(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_sendmsg.3compat.adoc b/docs/man/nn_sendmsg.3compat.adoc deleted file mode 100644 index b339bfe6..00000000 --- a/docs/man/nn_sendmsg.3compat.adoc +++ /dev/null @@ -1,107 +0,0 @@ -= nn_sendmsg(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_sendmsg - send message (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include <nanomsg/nn.h> - -int nn_sendmsg(int sock, const struct nn_msghdr *hdr, int flags); ----- - -== DESCRIPTION - -The `nn_sendmsg()` function sends the message described by _hdr_ using the -socket _sock_. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The _flags_ field may contain the special flag `NN_DONTWAIT`. -In this case, if the socket is unable to accept more data for sending, -the operation shall not block, but instead will fail with the error `EAGAIN`. - -The _hdr_ points to a structure of type `struct nn_msghdr`, which has the -following definition: - -[source, c] ----- -struct nn_iovec { - void * iov_base; - size_t iov_len; -}; - -struct nn_msghdr { - struct nn_iovec *msg_iov; - int msg_iovlen; - void * msg_control; - size_t msg_controllen; -}; ----- - -The `msg_iov` is an array of gather items, permitting the message -to be spread into different memory blocks. -There are `msg_iovlen` elements in this array, each of which -has the base address (`iov_base`) and length (`iov_len`) indicated. - -For buffers allocated for zero copy -(such as by xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]), the value -of `iov_base` should be the address of the pointer to the buffer, -rather than the address of the buffer itself. -In this case, the value of `iov_len` should be `NN_MSG`, -as the length is inferred from the allocated message. -If the `msg_iovlen` field is `NN_MSG`, then this function will free -the associated buffer after it is done with it, if it returns successfully. -(If the function returns with an error, then the caller retains ownership -of the associated buffer and may retry the operation or free the buffer -at its choice.) - -The values of `msg_control` and `msg_controllen` describe a buffer -of ancillary data to send the message. -This is currently only useful to provide the message headers -used with xref:nng.7.adoc#raw_mode[raw mode] sockets. -In all other circumstances these fields should be zero. -Details about this structure are covered in -xref:nn_cmsg.3compat.adoc[`nn_cmsg(3compat)`]. - -NOTE: The send operation is performed asynchronously, and may not have -completed before this function returns control to the caller. - -== RETURN VALUES - -This function returns the number of bytes sent on success, and -1 on error. - -== ERRORS - -[horizontal] -`EAGAIN`:: The operation would block. -`EBADF`:: The socket _sock_ is not open. -`EFSM`:: The socket cannot send in this state. -`EINVAL`:: The _hdr_ is invalid. -`ENOTSUP`:: This protocol cannot send. -`ETIMEDOUT`:: Operation timed out. - -== SEE ALSO - -[.text-left] -xref:nn_cmsg.3compat.adoc[nn_cmsg(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_recv.3compat.adoc[nn_recv(3compat)], -xref:nn_send.3compat.adoc[nn_send(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_setsockopt.3compat.adoc b/docs/man/nn_setsockopt.3compat.adoc deleted file mode 100644 index 860d522e..00000000 --- a/docs/man/nn_setsockopt.3compat.adoc +++ /dev/null @@ -1,205 +0,0 @@ -= nn_setsockopt(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_setsockopt - set socket option (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -int nn_setsockopt(int sock, int level, int option, const void *val, size_t sz); ----- - -== DESCRIPTION - -The `nn_setsockopt()` function sets a socket option on socket _sock_, -affecting the behavior of the socket. -The option set is determined by the _level_ and _option_. -The value of the option is set by _val_, and _sz_, which are pointers to -the actual value and the size of the value, respectively. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The _level_ determines whether the option is a generic socket option, -or is transport-specific. -The values possible for level are as follows: - -[horizontal] -`NN_SOL_SOCKET`:: Generic socket option -`NN_IPC`:: Transport specific option for IPC. -`NN_TCP`:: Transport specific option for TCP. -`NN_WS`:: Transport specific option for WebSocket. - -The following generic socket options are possible (all are of type `int` and -thus size 4, unless otherwise indicated.) - -`NN_SNDBUF`:: -Send buffer size in bytes. - -NOTE: In _NNG_ buffers are sized as a count of messages rather than -bytes, and so an attempt to estimate a conversion based upon a predetermined -message size of 1kB is made. -The value supplied is rounded up to the nearest value divisible by 1024, and -then divided by 1024 to convert to a message count. -Applications that have unusual message sizes may wish to adjust the value -used here accordingly. - -`NN_RCVBUF`:: -Receive buffer size in bytes. - -NOTE: The same caveats for `NN_SNDBUF` apply here as well. - -`NN_SNDTIMEO`:: -Send time-out in milliseconds. -Send operations will fail with `ETIMEDOUT` if no message can be received -after this many milliseconds have transpired since the operation was started. -A value of -1 means that no timeout is applied. - -`NN_RCVTIMEO`:: -Receive time-out in milliseconds. -Receive operations will fail with `ETIMEDOUT` if no message can be received -after this many milliseconds have transpired since the operation was started. -A value of -1 means that no timeout is applied. - -`NN_RCVMAXSIZE`:: -Maximum receive size in bytes. -The socket will discard messages larger than this on receive. -The default, 1MB, is intended to prevent denial-of-service attacks. -The value -1 removes any limit. - -`NN_RECONNECT_IVL`:: -Reconnect interval in milliseconds. -After an outgoing connection is closed or fails, the socket will -automatically attempt to reconnect after this many milliseconds. -This is the starting value for the time, and is used in the first -reconnection attempt after a successful connection is made. -The default is 100. - -`NN_RECONNECT_IVL_MAX`:: -Maximum reconnect interval in milliseconds. -Subsequent reconnection attempts after a failed attempt are made at -exponentially increasing intervals (back-off), but the interval is -capped by this value. -If this value is smaller than `NN_RECONNECT_IVL`, then no exponential -back-off is performed, and each reconnect interval will be determined -solely by `NN_RECONNECT_IVL`. -The default is zero. - -`NN_LINGER`:: -This option is ignored, and exists only for compatibility. - -NOTE: This option was unreliable in early releases of _libnanomsg_, and -is unsupported in _NNG_ and recent _libnanomsg_ releases. -Applications needing assurance of message delivery should either include an -explicit notification (automatic with the `NN_REQ` protocol) or allow -sufficient time for the socket to drain before closing the socket or exiting. - -`NN_SNDPRIO`:: -This option is not implemented at this time. - -`NN_RCVPRIO`:: -This option is not implemented at this time. - -`NN_IPV4ONLY`:: -This option is not implemented at this time. - -`NN_SOCKET_NAME`:: -This option is a string, and represents the socket name. -It can be changed to help with identifying different sockets with -their different application-specific purposes. - -`NN_MAXTTL`:: -Maximum number of times a message may traverse devices or proxies. -This value, if positive, provides some protection against forwarding loops in -xref:nng_device.3.adoc[device] chains. - -NOTE: Not all protocols offer this protection, so care should still be used -in configuring device forwarding. - -The following option is available for `NN_REQ` sockets -using the `NN_REQ` level: - -`NN_REQ_RESEND_IVL`:: -Request retry interval in milliseconds. -If an `NN_REQ` socket does not receive a reply to a request within this -period of time, the socket will automatically resend the request. -The default value is 60000 (one minute). - -The following options are available for `NN_SUB` sockets using the `NN_SUB` level: - -`NN_SUB_SUBSCRIBE`:: -Subscription topic, for `NN_SUB` sockets. -This sets a subscription topic. -When a message from a publisher arrives, it is compared against all -subscriptions. -If the first _sz_ bytes of the message are not identical to _val_, -then the message is silently discarded. - -TIP: To receive all messages, subscribe to an empty topic (_sz_ equal to zero). - -`NN_SUB_UNSUBSCRIBE`:: -Removes a subscription topic that was earlier established. - -The following option is available for `NN_SURVEYOR` sockets -using the `NN_SURVEYOR` level: - -`NN_SURVEYOR_DEADLINE`:: -Survey deadline in milliseconds for `NN_SURVEYOR` sockets. -After sending a survey message, the socket will only accept responses -from respondents for this long. -Any responses arriving after this expires are silently discarded. - -In addition, the following transport specific options are offered: - -`NN_IPC_SEC_ATTR`:: -This `NN_IPC` option is not supported at this time. - -`NN_IPC_OUTBUFSZ`:: -This `NN_IPC` option is not supported at this time. - -`NN_IPC_INBUFSZE`:: -This `NN_IPC` option is not supported at this time. - -`NN_TCP_NODELAY`:: -This `NN_TCP` option is not supported at this time. - -`NN_WS_MSG_TYPE`:: -This `NN_WS` option is not supported at this time. - -== RETURN VALUES - -This function returns zero on success, and -1 on failure. - -== ERRORS - -[horizontal] -`EBADF`:: The socket _sock_ is not an open socket. -`ENOMEM`:: Insufficient memory is available. -`ENOPROTOOPT`:: The level and/or option is invalid. -`EINVAL`:: The option, or the value passed, is invalid. -`ETERM`:: The library is shutting down. -`EACCES`:: The option cannot be changed. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nn_close.3compat.adoc[nn_close(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_getsockopt.3compat.adoc[nn_getsockopt(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_shutdown.3compat.adoc b/docs/man/nn_shutdown.3compat.adoc deleted file mode 100644 index 06a5cd5a..00000000 --- a/docs/man/nn_shutdown.3compat.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= nn_shutdown(3compat) -// -// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_shutdown - shut down endpoint (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include <nanomsg/nn.h> - -int nn_shutdown(int sock, int ep) ----- - -== DESCRIPTION - -The `nn_shutdown()` shuts down the endpoint _ep_, which is either a listener or -a dialer) on the socket _sock_. -This will stop the socket from either accepting new connections, or establishing -old ones. -Additionally, any established connections associated with _ep_ will be closed. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -== RETURN VALUES - -This function returns zero on success, and -1 on error. - -== ERRORS - -[horizontal] -`EBADF`:: The socket _sock_ is not open. -`EINVAL`:: An invalid _ep_ was supplied. - -== SEE ALSO - -[.text-left] -xref:nn_bind.3compat.adoc[nn_bind(3compat)], -xref:nn_connect.3compat.adoc[nn_connect(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_socket.3compat.adoc b/docs/man/nn_socket.3compat.adoc deleted file mode 100644 index c4bbb70a..00000000 --- a/docs/man/nn_socket.3compat.adoc +++ /dev/null @@ -1,78 +0,0 @@ -= nn_socket(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_socket - create socket (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -int nn_socket(int af, int proto); ----- - -== DESCRIPTION - -The `nn_socket()` function creates socket using the address family _af_ and -protocol _proto_ and returns it. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -IMPORTANT: Mixing the compatibility API and the modern API is not supported -on a given socket. - -NOTE: Some protocols, transports, and features are only available in the modern API. - -The address family _af_ can be one of two values: - -[horizontal] -`AF_SP`:: Normal socket. -`AF_SP_RAW`:: xref:nng.7.adoc#raw_mode[Raw mode] socket. - -The protocol indicates the protocol to be used when creating the socket. -The following protocols are defined: - -[horizontal] -`NN_PAIR`:: xref:nng_pair.7.adoc[Pair] protocol. -`NN_PUB`:: xref:nng_pub.7.adoc[Publisher] protocol. -`NN_SUB`:: xref:nng_sub.7.adoc[Subscriber] protocol. -`NN_REQ`:: xref:nng_req.7.adoc[Requestor] protocol. -`NN_REP`:: xref:nng_rep.7.adoc[Replier] protocol. -`NN_PUSH`:: xref:nng_push.7.adoc[Push] protocol. -`NN_PULL`:: xref:nng_pull.7.adoc[Pull] protocol. -`NN_SURVEYOR`:: xref:nng_surveyor.7.adoc[Surveyor] protocol. -`NN_RESPONDENT`:: xref:nng_respondent.7.adoc[Respondent] protocol. -`NN_BUS`:: xref:nng_bus.7.adoc[Bus] protocol. - -== RETURN VALUES - -This function returns a valid socket number on success, and -1 on failure. - -== ERRORS - -[horizontal] -`ENOMEM`:: Insufficient memory is available. -`ENOTSUP`:: The protocol is not supported. -`ETERM`:: The library is shutting down. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nn_close.3compat.adoc[nn_close(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_strerror.3compat.adoc b/docs/man/nn_strerror.3compat.adoc deleted file mode 100644 index 3fc2dc29..00000000 --- a/docs/man/nn_strerror.3compat.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nn_strerror(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_strerror - return message for error (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -const char *nn_strerror(int err); ----- - -== DESCRIPTION - -The `nn_strerror()` function returns a human readable message corresponding -to the given error number _err_. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -== RETURN VALUES - -This function returns the message corresponding to _err_. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_term.3compat.adoc b/docs/man/nn_term.3compat.adoc deleted file mode 100644 index 79b6a1e3..00000000 --- a/docs/man/nn_term.3compat.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nn_term(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_term - terminate library (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include <nanomsg/nn.h> - -void nn_term(void); ----- - -== DESCRIPTION - -The `nn_term()` function closes any open sockets, and frees all resources -allocated by the library. -Any operations that are currently in progress will be terminated, and will -fail with error `EBADF` or `ETERM`. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -IMPORTANT: This function is not thread-safe, and is not suitable for use -in library calls. -The intended purpose of this is to clean up at application termination; for -example by registering this function with `atexit()`. -This can help prevent false leak reports caused when memory checkers notice -global resources allocated by the library. -Libraries should never use this function, but should explicitly close their -own sockets directly. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_compat.3compat.adoc b/docs/man/nng_compat.3compat.adoc deleted file mode 100644 index bd986597..00000000 --- a/docs/man/nng_compat.3compat.adoc +++ /dev/null @@ -1,214 +0,0 @@ -= nng_compat(3compat) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_compat - compatibility with nanomsg 1.0 - -== SYNOPSIS - -[source, c] ----- -#include <nanomsg/nn.h> - -#include <nanomsg/bus.h> -#include <nanomsg/pair.h> -#include <nanomsg/pipeline.h> -#include <nanomsg/pubsub.h> -#include <nanomsg/reqrep.h> -#include <nanomsg/survey.h> - -#include <nanomsg/inproc.h> -#include <nanomsg/ipc.h> -#include <nanomsg/tcp.h> -#include <nanomsg/ws.h> ----- - -== DESCRIPTION - -(((compatibility layer))) -xref:nng.7.adoc[_NNG_] provides source-level compatibility for -most _libnanomsg_ 1.0 applications. - -IMPORTANT: This is intended to facilitate converting ((legacy applications)) to -use _NNG_. -New applications should use the newer xref:nng.7.adoc[_NNG_] API instead. - -Applications making use of this must take care -to link with xref:libnng.3.adoc[_libnng_] instead of _libnn_. - -TIP: While not recommended for long term use, the value returned by -xref:nng_socket_id.3.adoc[`nng_socket_id()`] can be used with these functions -just like a value returned by xref:nn_socket.3compat.adoc[`nn_socket()`]. -This can be way to facilitate incremental transition to the new API. - -NOTE: Some capabilities, protocols, and transports, will not be accessible -using this API, as the compatible API has no provision for expression -of certain concepts introduced in the new API. - -NOTE: While reasonable efforts have been made to provide for compatibility, -some things may behave differently, and some less common parts of the -_libnanomsg_ 1.0 API are not supported at this time, including certain -options and the statistics API. -See the <<Caveats>> section below. - -=== Compiling - -When compiling legacy _nanomsg_ applications, it will generally be -necessary to change the include search path to add the `compat` subdirectory -of the directory where headers were installed. -For example, if _NNG_ is installed in `$prefix`, then header files will -normally be located in `$prefix/include/nng`. -In this case, to build legacy _nanomsg_ apps against _NNG_ you would -add `$prefix/include/nng/compat` to your compiler's search path. - -Alternatively, you can change your source code so that `#include` statements -referring to `<nanomsg>` instead refer to `<nng/compat/nanomsg>`. -For example, instead of: - -[source,c] ----- -#include <nanomsg/nn.h> -#include <nanomsg/reqrep.h> ----- - -you would have this: - -[source,c] ----- -#include <nng/compat/nanomsg/nn.h> -#include <nng/compat/nanomsg/reqrep.h> ----- - -Legacy applications built using these methods should be linked against _libnng_ -instead of _libnn_, just like any other _NNG_ application. - -=== Functions - -The following functions are provided: - -// For PDF, we don't have horizontal lists, so we have to conditionalize -// this and use tables there -- it looks ugly otherwise. -ifndef::backend-pdf[] -[horizontal] -xref:nn_socket.3compat.adoc[`nn_socket()`]:: create socket -xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`]:: get socket option -xref:nn_setsockopt.3compat.adoc[`nn_setsockopt()`]:: set socket option -xref:nn_bind.3compat.adoc[`nn_bind()`]:: accept connections from remote peers -xref:nn_connect.3compat.adoc[`nn_connect()`]:: connect to remote peer -xref:nn_send.3compat.adoc[`nn_send()`]:: send data -xref:nn_recv.3compat.adoc[`nn_recv()`]:: receive data -xref:nn_shutdown.3compat.adoc[`nn_shutdown()`]:: shut down endpoint -xref:nn_close.3compat.adoc[`nn_close()`]:: close socket -xref:nn_poll.3compat.adoc[`nn_poll()`]:: poll sockets -xref:nn_device.3compat.adoc[`nn_device()`]:: create forwarding device -xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]:: receive message -xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`]:: send message -xref:nn_cmsg.3compat.adoc[`nn_cmsg()`]:: message control data -xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]:: get statistic (stub) -xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]:: allocate message -xref:nn_reallocmsg.3compat.adoc[`nn_reallocmsg()`]:: reallocate message -xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]:: free message -xref:nn_errno.3compat.adoc[`nn_errno()`]:: return most recent error -xref:nn_strerror.3compat.adoc[`nn_strerror()`]:: return message for error -xref:nn_term.3compat.adoc[`nn_term()`]:: terminate library -endif::[] -ifdef::backend-pdf[] -// Add links for the following as they are written. -[.hdlist,width=90%, grid=rows,cols="1,2", align="center"] -|=== -|xref:nn_socket.3compat.adoc[`nn_socket()`]|create socket -|xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`]|get socket option -|xref:nn_setsockopt.3compat.adoc[`nn_setsockopt()`]|set socket option -|xref:nn_bind.3compat.adoc[`nn_bind()`]|accept connections from remote peers -|xref:nn_connect.3compat.adoc[`nn_connect()`]|connect to remote peer -|xref:nn_send.3compat.adoc[`nn_send()`]|send data -|xref:nn_recv.3compat.adoc[`nn_recv()`]|receive data -|xref:nn_shutdown.3compat.adoc[`nn_shutdown()`]|shut down endpoint -|xref:nn_close.3compat.adoc[`nn_close()`]|close socket -|xref:nn_poll.3compat.adoc[`nn_poll()`]|poll sockets -|xref:nn_device.3compat.adoc[`nn_device()`]|create forwarding device -|xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]|receive message -|xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`]|send message -|xref:nn_cmsg.3compat.adoc[`nn_cmsg()`]|message control data -|xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]|get statistic (stub) -|xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]|allocate message -|xref:nn_reallocmsg.3compat.adoc[`nn_reallocmsg()`]|reallocate message -|xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]|free message -|xref:nn_errno.3compat.adoc[`nn_errno()`]|return most recent error -|xref:nn_strerror.3compat.adoc[`nn_strerror()`]|return message for error -|xref:nn_term.3compat.adoc[`nn_term()`]|terminate library -|=== -endif::[] - -=== Caveats - -The following caveats apply when using the legacy API with _NNG_. - -* Socket numbers can be quite large. - The legacy _libnanomsg_ attempted to reuse socket numbers, like - file descriptors in UNIX systems. - _NNG_ avoids this to prevent accidental reuse or - collision after a descriptor is closed. - Consequently, socket numbers can become quite large, and should - probably not be used for array indices. - -* The following options (`nn_getsockopt`) are unsupported: - `NN_SNDPRIO`, `NN_RCVPRIO`, `NN_IPV4ONLY`. - The priority options may be supported in the future, when - the underlying capability is present in _NNG_. - -* Access to statistics using this legacy API - (xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]) is unsupported. - -* Some transports can support longer URLs than legacy _libnanomsg_ can. - It is a good idea to use short pathnames in URLs if interoperability - is a concern. - -* Only absolute paths are supported in `ipc://` URLs. - For example, `ipc:///tmp/mysocket` is acceptable, but `ipc://mysocket` is not. - -* The WebSocket transport in this implementation (`ws://` URLs) - only supports BINARY frames. - -* Some newer transports are unusable from this mode. - In particular, this legacy API offers no way to configure - TLS or ZeroTier parameters that may be required for use. - -* ABI versioning of the compatibility layer is not supported, - and the `NN_VERSION_` macros are not present. - -* Runtime symbol information is not implemented. - Specifically, there is no `nn_symbol()` function yet. - (This may be addressed later if there is a need.) - -* The TCP transport (`tcp://` URLs) does not support specifying the local - address or interface when binding. (This could be fixed in the future, - but most likely this will be available only using the new API.) - -* The values of `NN_RCVMAXSIZE` are constrained. - Specifically, values set larger than 2GB using the new API will be reported - as unlimited (`-1`) in the new API, and the value `0` will disable any - enforcement, just like `-1`. - (There is no practical reason to ever want to limit the receive size to - zero.) - -* This implementation counts buffers in terms of messages rather than bytes. - As a result, the buffer sizes accessed with `NN_SNDBUF` and `NN_RCVBUF` are - rounded up to a whole number of kilobytes, then divided by 1024, in order - to approximate buffering assuming 1 KB messages. - Few applications should need to adjust the default values. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng.7.adoc[nng(7)] |