From 6f8944a96a5acd509014caae4e57dafbba51e126 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 30 Mar 2024 22:14:33 -0700 Subject: finished proto open pages --- docs/man/nn_allocmsg.3compat.adoc | 67 ------ docs/man/nn_bind.3compat.adoc | 68 ------ docs/man/nn_close.3compat.adoc | 51 ----- docs/man/nn_cmsg.3compat.adoc | 78 ------- docs/man/nn_connect.3compat.adoc | 67 ------ docs/man/nn_device.3compat.adoc | 59 ------ docs/man/nn_errno.3compat.adoc | 79 ------- docs/man/nn_freemsg.3compat.adoc | 49 ----- docs/man/nn_get_statistic.3compat.adoc | 46 ----- docs/man/nn_getsockopt.3compat.adoc | 228 --------------------- docs/man/nn_poll.3compat.adoc | 102 --------- docs/man/nn_reallocmsg.3compat.adoc | 59 ------ docs/man/nn_recv.3compat.adoc | 75 ------- docs/man/nn_recvmsg.3compat.adoc | 99 --------- docs/man/nn_send.3compat.adoc | 74 ------- docs/man/nn_sendmsg.3compat.adoc | 107 ---------- docs/man/nn_setsockopt.3compat.adoc | 205 ------------------ docs/man/nn_shutdown.3compat.adoc | 55 ----- docs/man/nn_socket.3compat.adoc | 78 ------- docs/man/nn_strerror.3compat.adoc | 47 ----- docs/man/nn_term.3compat.adoc | 59 ------ docs/reference/book.toml | 6 +- docs/reference/src/SUMMARY.md | 3 + docs/reference/src/compat/nn_allocmsg.3compat.adoc | 67 ++++++ docs/reference/src/compat/nn_bind.3compat.adoc | 68 ++++++ docs/reference/src/compat/nn_close.3compat.adoc | 51 +++++ docs/reference/src/compat/nn_cmsg.3compat.adoc | 78 +++++++ docs/reference/src/compat/nn_connect.3compat.adoc | 67 ++++++ docs/reference/src/compat/nn_device.3compat.adoc | 59 ++++++ docs/reference/src/compat/nn_errno.3compat.adoc | 79 +++++++ docs/reference/src/compat/nn_freemsg.3compat.adoc | 49 +++++ .../src/compat/nn_get_statistic.3compat.adoc | 46 +++++ .../src/compat/nn_getsockopt.3compat.adoc | 228 +++++++++++++++++++++ docs/reference/src/compat/nn_poll.3compat.adoc | 102 +++++++++ .../src/compat/nn_reallocmsg.3compat.adoc | 59 ++++++ docs/reference/src/compat/nn_recv.3compat.adoc | 75 +++++++ docs/reference/src/compat/nn_recvmsg.3compat.adoc | 99 +++++++++ docs/reference/src/compat/nn_send.3compat.adoc | 74 +++++++ docs/reference/src/compat/nn_sendmsg.3compat.adoc | 107 ++++++++++ .../src/compat/nn_setsockopt.3compat.adoc | 205 ++++++++++++++++++ docs/reference/src/compat/nn_shutdown.3compat.adoc | 55 +++++ docs/reference/src/compat/nn_socket.3compat.adoc | 78 +++++++ docs/reference/src/compat/nn_strerror.3compat.adoc | 47 +++++ docs/reference/src/compat/nn_term.3compat.adoc | 59 ++++++ docs/reference/src/sock/nng_bus_open.md | 4 +- docs/reference/src/sock/nng_pair_open.md | 2 +- docs/reference/src/sock/nng_pub_open.md | 2 +- docs/reference/src/sock/nng_pull_open.md | 2 +- docs/reference/src/sock/nng_push_open.md | 4 +- docs/reference/src/sock/nng_rep_open.3.adoc | 42 ---- docs/reference/src/sock/nng_rep_open.md | 41 ++++ docs/reference/src/sock/nng_req_open.3.adoc | 44 ---- docs/reference/src/sock/nng_req_open.md | 41 ++++ docs/reference/src/sock/nng_respondent_open.3.adoc | 45 ---- docs/reference/src/sock/nng_respondent_open.md | 42 ++++ docs/reference/src/sock/nng_sub_open.md | 2 +- docs/reference/src/sock/nng_surveyor_open.md | 2 +- 57 files changed, 1889 insertions(+), 1897 deletions(-) delete mode 100644 docs/man/nn_allocmsg.3compat.adoc delete mode 100644 docs/man/nn_bind.3compat.adoc delete mode 100644 docs/man/nn_close.3compat.adoc delete mode 100644 docs/man/nn_cmsg.3compat.adoc delete mode 100644 docs/man/nn_connect.3compat.adoc delete mode 100644 docs/man/nn_device.3compat.adoc delete mode 100644 docs/man/nn_errno.3compat.adoc delete mode 100644 docs/man/nn_freemsg.3compat.adoc delete mode 100644 docs/man/nn_get_statistic.3compat.adoc delete mode 100644 docs/man/nn_getsockopt.3compat.adoc delete mode 100644 docs/man/nn_poll.3compat.adoc delete mode 100644 docs/man/nn_reallocmsg.3compat.adoc delete mode 100644 docs/man/nn_recv.3compat.adoc delete mode 100644 docs/man/nn_recvmsg.3compat.adoc delete mode 100644 docs/man/nn_send.3compat.adoc delete mode 100644 docs/man/nn_sendmsg.3compat.adoc delete mode 100644 docs/man/nn_setsockopt.3compat.adoc delete mode 100644 docs/man/nn_shutdown.3compat.adoc delete mode 100644 docs/man/nn_socket.3compat.adoc delete mode 100644 docs/man/nn_strerror.3compat.adoc delete mode 100644 docs/man/nn_term.3compat.adoc create mode 100644 docs/reference/src/compat/nn_allocmsg.3compat.adoc create mode 100644 docs/reference/src/compat/nn_bind.3compat.adoc create mode 100644 docs/reference/src/compat/nn_close.3compat.adoc create mode 100644 docs/reference/src/compat/nn_cmsg.3compat.adoc create mode 100644 docs/reference/src/compat/nn_connect.3compat.adoc create mode 100644 docs/reference/src/compat/nn_device.3compat.adoc create mode 100644 docs/reference/src/compat/nn_errno.3compat.adoc create mode 100644 docs/reference/src/compat/nn_freemsg.3compat.adoc create mode 100644 docs/reference/src/compat/nn_get_statistic.3compat.adoc create mode 100644 docs/reference/src/compat/nn_getsockopt.3compat.adoc create mode 100644 docs/reference/src/compat/nn_poll.3compat.adoc create mode 100644 docs/reference/src/compat/nn_reallocmsg.3compat.adoc create mode 100644 docs/reference/src/compat/nn_recv.3compat.adoc create mode 100644 docs/reference/src/compat/nn_recvmsg.3compat.adoc create mode 100644 docs/reference/src/compat/nn_send.3compat.adoc create mode 100644 docs/reference/src/compat/nn_sendmsg.3compat.adoc create mode 100644 docs/reference/src/compat/nn_setsockopt.3compat.adoc create mode 100644 docs/reference/src/compat/nn_shutdown.3compat.adoc create mode 100644 docs/reference/src/compat/nn_socket.3compat.adoc create mode 100644 docs/reference/src/compat/nn_strerror.3compat.adoc create mode 100644 docs/reference/src/compat/nn_term.3compat.adoc delete mode 100644 docs/reference/src/sock/nng_rep_open.3.adoc create mode 100644 docs/reference/src/sock/nng_rep_open.md delete mode 100644 docs/reference/src/sock/nng_req_open.3.adoc create mode 100644 docs/reference/src/sock/nng_req_open.md delete mode 100644 docs/reference/src/sock/nng_respondent_open.3.adoc create mode 100644 docs/reference/src/sock/nng_respondent_open.md 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. -// 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 - -nn_allocmsg - allocate message (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -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. -// 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 - -nn_bind - accept connections from remote peers (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// 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 - -nn_close - close socket (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -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. -// 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 - -nn_cmsg - message control data (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -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. -// 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 - -nn_connect - connect to remote peer (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// 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 - -nn_device - create forwarding device (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -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. -// 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 - -nn_errno - return most recent error (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -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. -// 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 - -nn_freemsg - free message (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -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. -// 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 - -nn_get_statistic - get statistic (stub) - -== SYNOPSIS - -[source,c] ----- -#include - -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. -// 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 - -nn_getsockopt - get socket option (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -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. -// 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 - -nn_poll - poll sockets (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -#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. -// 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 - -nn_reallocmsg - reallocate message (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -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. -// 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 - -nn_recv - receive data (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// 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 - -nn_recvmsg - receive message (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// 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 - -nn_send - send data (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// 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 - -nn_sendmsg - send message (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// 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 - -nn_setsockopt - set socket option (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -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. -// 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 - -nn_shutdown - shut down endpoint (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -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. -// 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 - -nn_socket - create socket (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -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. -// 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 - -nn_strerror - return message for error (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -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. -// 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 - -nn_term - terminate library (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -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/reference/book.toml b/docs/reference/book.toml index 20529827..aeca51c3 100644 --- a/docs/reference/book.toml +++ b/docs/reference/book.toml @@ -14,13 +14,9 @@ fold.level = 1 [preprocessor.indexing.see_instead] -# "*PULL* protocol" = "protocol, *PULL*" - -#"protocol, PUB" = "PUB" -# "_PAIR_‍" = "protocol, _PAIR_" +# "*PUSH* (protocol)" = "protocol, *PUSH*" [preprocessor.indexing.nest_under] -# hacks to allow us to also place some entries underneath "body" = "message" "header" = "message" diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index 498511a4..82187252 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -58,6 +58,9 @@ - [nng_pub_open](sock/nng_pub_open.md) - [nng_pull_open](sock/nng_pull_open.md) - [nng_push_open](sock/nng_push_open.md) + - [nng_respondent_open](sock/nng_respondent_open.md) + - [nng_rep_open](sock/nng_rep_open.md) + - [nng_req_open](sock/nng_req_open.md) - [nng_sub_open](sock/nng_sub_open.md) - [nng_surveyor_open](sock/nng_surveyor_open.md) diff --git a/docs/reference/src/compat/nn_allocmsg.3compat.adoc b/docs/reference/src/compat/nn_allocmsg.3compat.adoc new file mode 100644 index 00000000..a53da55c --- /dev/null +++ b/docs/reference/src/compat/nn_allocmsg.3compat.adoc @@ -0,0 +1,67 @@ += nn_allocmsg(3compat) +// +// 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 + +nn_allocmsg - allocate message (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/compat/nn_bind.3compat.adoc b/docs/reference/src/compat/nn_bind.3compat.adoc new file mode 100644 index 00000000..a4ca0043 --- /dev/null +++ b/docs/reference/src/compat/nn_bind.3compat.adoc @@ -0,0 +1,68 @@ += nn_bind(3compat) +// +// 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 + +nn_bind - accept connections from remote peers (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +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/reference/src/compat/nn_close.3compat.adoc b/docs/reference/src/compat/nn_close.3compat.adoc new file mode 100644 index 00000000..1970b57d --- /dev/null +++ b/docs/reference/src/compat/nn_close.3compat.adoc @@ -0,0 +1,51 @@ += nn_close(3compat) +// +// 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 + +nn_close - close socket (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/compat/nn_cmsg.3compat.adoc b/docs/reference/src/compat/nn_cmsg.3compat.adoc new file mode 100644 index 00000000..32d31810 --- /dev/null +++ b/docs/reference/src/compat/nn_cmsg.3compat.adoc @@ -0,0 +1,78 @@ += nn_cmsg(3compat) +// +// 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 + +nn_cmsg - message control data (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/compat/nn_connect.3compat.adoc b/docs/reference/src/compat/nn_connect.3compat.adoc new file mode 100644 index 00000000..e498f8d3 --- /dev/null +++ b/docs/reference/src/compat/nn_connect.3compat.adoc @@ -0,0 +1,67 @@ += nn_connect(3compat) +// +// 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 + +nn_connect - connect to remote peer (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +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/reference/src/compat/nn_device.3compat.adoc b/docs/reference/src/compat/nn_device.3compat.adoc new file mode 100644 index 00000000..c69e1e04 --- /dev/null +++ b/docs/reference/src/compat/nn_device.3compat.adoc @@ -0,0 +1,59 @@ += nn_device(3compat) +// +// 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 + +nn_device - create forwarding device (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/compat/nn_errno.3compat.adoc b/docs/reference/src/compat/nn_errno.3compat.adoc new file mode 100644 index 00000000..a048543d --- /dev/null +++ b/docs/reference/src/compat/nn_errno.3compat.adoc @@ -0,0 +1,79 @@ += nn_errno(3compat) +// +// 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 + +nn_errno - return most recent error (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/compat/nn_freemsg.3compat.adoc b/docs/reference/src/compat/nn_freemsg.3compat.adoc new file mode 100644 index 00000000..61127c3d --- /dev/null +++ b/docs/reference/src/compat/nn_freemsg.3compat.adoc @@ -0,0 +1,49 @@ += nn_freemsg(3compat) +// +// 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 + +nn_freemsg - free message (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/compat/nn_get_statistic.3compat.adoc b/docs/reference/src/compat/nn_get_statistic.3compat.adoc new file mode 100644 index 00000000..89b11de2 --- /dev/null +++ b/docs/reference/src/compat/nn_get_statistic.3compat.adoc @@ -0,0 +1,46 @@ += nn_get_statistic(3compat) +// +// 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 + +nn_get_statistic - get statistic (stub) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/compat/nn_getsockopt.3compat.adoc b/docs/reference/src/compat/nn_getsockopt.3compat.adoc new file mode 100644 index 00000000..0c476cca --- /dev/null +++ b/docs/reference/src/compat/nn_getsockopt.3compat.adoc @@ -0,0 +1,228 @@ += nn_getsockopt(3compat) +// +// 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 + +nn_getsockopt - get socket option (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/compat/nn_poll.3compat.adoc b/docs/reference/src/compat/nn_poll.3compat.adoc new file mode 100644 index 00000000..c115fe49 --- /dev/null +++ b/docs/reference/src/compat/nn_poll.3compat.adoc @@ -0,0 +1,102 @@ += nn_poll(3compat) +// +// 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 + +nn_poll - poll sockets (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +#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/reference/src/compat/nn_reallocmsg.3compat.adoc b/docs/reference/src/compat/nn_reallocmsg.3compat.adoc new file mode 100644 index 00000000..d48b5d40 --- /dev/null +++ b/docs/reference/src/compat/nn_reallocmsg.3compat.adoc @@ -0,0 +1,59 @@ += nn_reallocmsg(3compat) +// +// 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 + +nn_reallocmsg - reallocate message (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/compat/nn_recv.3compat.adoc b/docs/reference/src/compat/nn_recv.3compat.adoc new file mode 100644 index 00000000..2a71714d --- /dev/null +++ b/docs/reference/src/compat/nn_recv.3compat.adoc @@ -0,0 +1,75 @@ += nn_recv(3compat) +// +// 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 + +nn_recv - receive data (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +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/reference/src/compat/nn_recvmsg.3compat.adoc b/docs/reference/src/compat/nn_recvmsg.3compat.adoc new file mode 100644 index 00000000..e0fcc758 --- /dev/null +++ b/docs/reference/src/compat/nn_recvmsg.3compat.adoc @@ -0,0 +1,99 @@ += nn_recvmsg(3compat) +// +// 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 + +nn_recvmsg - receive message (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +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/reference/src/compat/nn_send.3compat.adoc b/docs/reference/src/compat/nn_send.3compat.adoc new file mode 100644 index 00000000..050bea17 --- /dev/null +++ b/docs/reference/src/compat/nn_send.3compat.adoc @@ -0,0 +1,74 @@ += nn_send(3compat) +// +// 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 + +nn_send - send data (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +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/reference/src/compat/nn_sendmsg.3compat.adoc b/docs/reference/src/compat/nn_sendmsg.3compat.adoc new file mode 100644 index 00000000..b339bfe6 --- /dev/null +++ b/docs/reference/src/compat/nn_sendmsg.3compat.adoc @@ -0,0 +1,107 @@ += nn_sendmsg(3compat) +// +// 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 + +nn_sendmsg - send message (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +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/reference/src/compat/nn_setsockopt.3compat.adoc b/docs/reference/src/compat/nn_setsockopt.3compat.adoc new file mode 100644 index 00000000..860d522e --- /dev/null +++ b/docs/reference/src/compat/nn_setsockopt.3compat.adoc @@ -0,0 +1,205 @@ += nn_setsockopt(3compat) +// +// 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 + +nn_setsockopt - set socket option (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/compat/nn_shutdown.3compat.adoc b/docs/reference/src/compat/nn_shutdown.3compat.adoc new file mode 100644 index 00000000..06a5cd5a --- /dev/null +++ b/docs/reference/src/compat/nn_shutdown.3compat.adoc @@ -0,0 +1,55 @@ += nn_shutdown(3compat) +// +// 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 + +nn_shutdown - shut down endpoint (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include + +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/reference/src/compat/nn_socket.3compat.adoc b/docs/reference/src/compat/nn_socket.3compat.adoc new file mode 100644 index 00000000..c4bbb70a --- /dev/null +++ b/docs/reference/src/compat/nn_socket.3compat.adoc @@ -0,0 +1,78 @@ += nn_socket(3compat) +// +// 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 + +nn_socket - create socket (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/compat/nn_strerror.3compat.adoc b/docs/reference/src/compat/nn_strerror.3compat.adoc new file mode 100644 index 00000000..3fc2dc29 --- /dev/null +++ b/docs/reference/src/compat/nn_strerror.3compat.adoc @@ -0,0 +1,47 @@ += nn_strerror(3compat) +// +// 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 + +nn_strerror - return message for error (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/compat/nn_term.3compat.adoc b/docs/reference/src/compat/nn_term.3compat.adoc new file mode 100644 index 00000000..79b6a1e3 --- /dev/null +++ b/docs/reference/src/compat/nn_term.3compat.adoc @@ -0,0 +1,59 @@ += nn_term(3compat) +// +// 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 + +nn_term - terminate library (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include + +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/reference/src/sock/nng_bus_open.md b/docs/reference/src/sock/nng_bus_open.md index 9b993f52..0d37e86c 100644 --- a/docs/reference/src/sock/nng_bus_open.md +++ b/docs/reference/src/sock/nng_bus_open.md @@ -17,7 +17,7 @@ int nng_bus0_open_raw(nng_socket *s); ## DESCRIPTION -The `nng_bus0_open()` function creates a [_BUS_][bus] version 0 +The `nng_bus0_open()` function creates a [{{i:*BUS*}}][bus] version 0 [socket][socket] and returns it at the location pointed to by _s_. The `nng_bus0_open_raw()` function creates a _BUS_ version 0 @@ -34,7 +34,7 @@ These functions return 0 on success, and non-zero otherwise. ## SEE ALSO -[BUS protocol][bus], +[_BUS_ protocol][bus], [RAW mode][raw] {{#include ../refs.md}} diff --git a/docs/reference/src/sock/nng_pair_open.md b/docs/reference/src/sock/nng_pair_open.md index df3c8b65..fe955df5 100644 --- a/docs/reference/src/sock/nng_pair_open.md +++ b/docs/reference/src/sock/nng_pair_open.md @@ -29,7 +29,7 @@ int nng_pair1_open_poly(nng_socktet *s); ## DESCRIPTION The `nng_pair0_open()` and `nng_pair1_open()` functions -create a [_PAIR_][pair] version 0 or version 1 +create a [{{i:*PAIR*}}][pair] version 0 or version 1 [socket][socket] and return it at the location pointed to by _s_. The `nng_pair0_open_raw()` and `nng_pair1_open_raw()` functions diff --git a/docs/reference/src/sock/nng_pub_open.md b/docs/reference/src/sock/nng_pub_open.md index e8b6bbd0..0969f4d9 100644 --- a/docs/reference/src/sock/nng_pub_open.md +++ b/docs/reference/src/sock/nng_pub_open.md @@ -17,7 +17,7 @@ int nng_pub0_open_raw(nng_socket *s); ## DESCRIPTION -The `nng_pub0_open()` function creates a [_PUB_][pub] version 0 +The `nng_pub0_open()` function creates a [{{i:*PUB*}}][pub] version 0 [socket][socket] and returns it at the location pointed to by _s_. The `nng_pub0_open_raw()` function creates a _PUB_ version 0 diff --git a/docs/reference/src/sock/nng_pull_open.md b/docs/reference/src/sock/nng_pull_open.md index e10f66c0..53248207 100644 --- a/docs/reference/src/sock/nng_pull_open.md +++ b/docs/reference/src/sock/nng_pull_open.md @@ -17,7 +17,7 @@ int nng_pull0_open_raw(nng_socket *s); ## DESCRIPTION -The `nng_pull0_open()` function creates a [_PULL_][pull] version 0 +The `nng_pull0_open()` function creates a [{{i:*PULL*}}][pull] version 0 [socket][socket] and returns it at the location pointed to by _s_. The `nng_pull0_open_raw()` function creates a _PULL_ version 0 diff --git a/docs/reference/src/sock/nng_push_open.md b/docs/reference/src/sock/nng_push_open.md index aace8750..aed86f73 100644 --- a/docs/reference/src/sock/nng_push_open.md +++ b/docs/reference/src/sock/nng_push_open.md @@ -2,7 +2,7 @@ ## NAME -nng_push_open --- create push socket +nng_push_open --- create _PUSH_ socket ## SYNOPSIS @@ -17,7 +17,7 @@ int nng_push0_open_raw(nng_socket *s); ## DESCRIPTION -The `nng_push0_open()` function creates a [_PUSH_][push] version 0 +The `nng_push0_open()` function creates a [{{i:*PUSH*}}][push] version 0 [socket][socket] and returns it at the location pointed to by _s_. The `nng_push0_open_raw()` function creates a _PUSH_ version 0 socket in diff --git a/docs/reference/src/sock/nng_rep_open.3.adoc b/docs/reference/src/sock/nng_rep_open.3.adoc deleted file mode 100644 index 3b56c541..00000000 --- a/docs/reference/src/sock/nng_rep_open.3.adoc +++ /dev/null @@ -1,42 +0,0 @@ -# nng_rep_open(3) - -## NAME - -nng_rep_open - create rep socket - -## SYNOPSIS - -``` -#include -#include - -int nng_rep0_open(nng_socket *s); - -int nng_rep0_open_raw(nng_socket *); -``` - -## DESCRIPTION - -The `nng_rep0_open()` function creates a xref:nng_rep.7.adoc[_rep_] version 0 -xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_. - -The `nng_rep0_open_raw()` function creates a xref:nng_rep.7.adoc[_rep_] version 0 -xref:nng_socket.5.adoc[socket] -in xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -## SEE ALSO - -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_rep.7.adoc[nng_rep(7)], -xref:nng_req.7.adoc[nng_req(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/sock/nng_rep_open.md b/docs/reference/src/sock/nng_rep_open.md new file mode 100644 index 00000000..8472da7b --- /dev/null +++ b/docs/reference/src/sock/nng_rep_open.md @@ -0,0 +1,41 @@ +# nng_rep_open + +## NAME + +nng_rep_open --- create _REP_ socket + +## SYNOPSIS + +```c +#include +#include + +int nng_rep0_open(nng_socket *s); + +int nng_rep0_open_raw(nng_socket *); +``` + +## DESCRIPTION + +The `nng_rep0_open()` function creates a [{{i:*REP*}}][rep] version 0 +[socket][socket] and returns it at the location pointed to by _s_. + +The `nng_rep0_open_raw()` function creates a _REP_ version 0 +socket in [raw mode][raw] and returns it at the location pointed to by _s_. + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +* `NNG_ENOMEM`: Insufficient memory is available. +* `NNG_ENOTSUP`: The protocol is not supported. + +## SEE ALSO + +[Sockets][socket], +[_REP_ Protocol][rep], +[_REQ_ Protocol][req] + +{{#include ../refs.md}} diff --git a/docs/reference/src/sock/nng_req_open.3.adoc b/docs/reference/src/sock/nng_req_open.3.adoc deleted file mode 100644 index 51d1df8a..00000000 --- a/docs/reference/src/sock/nng_req_open.3.adoc +++ /dev/null @@ -1,44 +0,0 @@ -# nng_req_open(3) - -## NAME - -nng_req_open - create req socket - -## SYNOPSIS - -``` -#include -#include - -int nng_req0_open(nng_socket *s); - -int nng_req0_open_raw(nng_socket *s); -``` - -## DESCRIPTION - -The `nng_req0_open()` function creates a xref:nng_req.7.adoc[_req_] version 0 -xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_. - -The `nng_req0_open_raw()` function creates a xref:nng_req.7.adoc[_req_] version 0 -xref:nng_socket.5.adoc[socket] in -xref:nng.7.adoc#raw_mode[raw] mode -and returns it at the location pointed to by _s_. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -## SEE ALSO - -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_rep.7.adoc[nng_rep(7)], -xref:nng_req.7.adoc[nng_req(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/sock/nng_req_open.md b/docs/reference/src/sock/nng_req_open.md new file mode 100644 index 00000000..6763c00b --- /dev/null +++ b/docs/reference/src/sock/nng_req_open.md @@ -0,0 +1,41 @@ +# nng_req_open + +## NAME + +nng_req_open --- create req socket + +## SYNOPSIS + +```c +#include +#include + +int nng_req0_open(nng_socket *s); + +int nng_req0_open_raw(nng_socket *s); +``` + +## DESCRIPTION + +The `nng_req0_open()` function creates a [{{i:*REQ*}}][req] version 0 +[socket][socket] and returns it at the location pointed to by _s_. + +The `nng_req0_open_raw()` function creates a _REQ_ version 0 +socket in [raw mode][raw] and returns it at the location pointed to by _s_. + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +* `NNG_ENOMEM`: Insufficient memory is available. +* `NNG_ENOTSUP`: The protocol is not supported. + +## SEE ALSO + +[Sockets][socket], +[_REP_ Protocol][rep], +[_REQ_ Protocol][req] + +{{#include ../refs.md}} diff --git a/docs/reference/src/sock/nng_respondent_open.3.adoc b/docs/reference/src/sock/nng_respondent_open.3.adoc deleted file mode 100644 index 7a1fd6d9..00000000 --- a/docs/reference/src/sock/nng_respondent_open.3.adoc +++ /dev/null @@ -1,45 +0,0 @@ -# nng_respondent_open(3) - -## NAME - -nng_respondent_open - create respondent socket - -## SYNOPSIS - -``` -#include -#include - -int nng_respondent0_open(nng_socket *s); - -int nng_respondent0_open_raw(nng_socket *s); -``` - -## DESCRIPTION - -The `nng_respondent0_open()` function creates a -xref:nng_respondent.7.adoc[_respondent_] -version 0 xref:nng_socket.5.adoc[socket] and returns it at the location -pointed to by _s_. - -The `nng_respondent0_open_raw()` function creates a -xref:nng_respondent.7.adoc[_respondent_] -version 0 xref:nng_socket.5.adoc[socket] in -xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol is not supported. - -## SEE ALSO - -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng_respondent.7.adoc[nng_respondent(7)], -xref:nng_surveyor.7.adoc[nng_surveyor(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/sock/nng_respondent_open.md b/docs/reference/src/sock/nng_respondent_open.md new file mode 100644 index 00000000..b8883d8d --- /dev/null +++ b/docs/reference/src/sock/nng_respondent_open.md @@ -0,0 +1,42 @@ +# nng_respondent_open + +## NAME + +nng_respondent_open --- create _RESPONDENT_ socket + +## SYNOPSIS + +```c +#include +#include + +int nng_respondent0_open(nng_socket *s); + +int nng_respondent0_open_raw(nng_socket *s); +``` + +## DESCRIPTION + +The `nng_respondent0_open()` function creates a [{{i:*RESPONDENT*}}][respondent] +version 0 [socket][socket] and returns it at the location +pointed to by _s_. + +The `nng_respondent0_open_raw()` function creates a _RESPONDENT_ +version 0 socket in [raw mode][raw] and returns it at the location pointed to by _s_. + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +* `NNG_ENOMEM`: Insufficient memory is available. +* `NNG_ENOTSUP`: The protocol is not supported. + +## SEE ALSO + +[Sockets][socket], +[_RESPONDENT_ Protocol][respondent], +[_SURVEYOR_ Protocol][surveyor] + +{{#include ../refs.md}} diff --git a/docs/reference/src/sock/nng_sub_open.md b/docs/reference/src/sock/nng_sub_open.md index d98ecb7f..47adb00b 100644 --- a/docs/reference/src/sock/nng_sub_open.md +++ b/docs/reference/src/sock/nng_sub_open.md @@ -17,7 +17,7 @@ int nng_sub0_open_raw(nng_socket *s); ## DESCRIPTION -The `nng_sub0_open()` function creates a [_SUB_][sub] version 0 +The `nng_sub0_open()` function creates a [{{i:*SUB*}}][sub] version 0 [socket][socket] and returns it at the location pointed to by _s_. The `nng_sub0_open_raw()` function creates a _SUB_ version 0 diff --git a/docs/reference/src/sock/nng_surveyor_open.md b/docs/reference/src/sock/nng_surveyor_open.md index 77ac08ae..a09325ba 100644 --- a/docs/reference/src/sock/nng_surveyor_open.md +++ b/docs/reference/src/sock/nng_surveyor_open.md @@ -17,7 +17,7 @@ int nng_surveyor0_open_raw(nng_socket *s); ## DESCRIPTION -The `nng_surveyor0_open()` function creates a [_SURVEYOR_][surveyor] +The `nng_surveyor0_open()` function creates a [{{i:*SURVEYOR*}}][surveyor] version 0 [socket][socket] and returns it at the location pointed to by _s_. -- cgit v1.2.3-70-g09d2