diff options
Diffstat (limited to 'docs/reference')
36 files changed, 1889 insertions, 145 deletions
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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_allocmsg - allocate message (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +void *nn_allocmsg(size_t size, int type); +---- + +== DESCRIPTION + +The `nn_allocmsg()` allocates a message structure of size _size_, and is +primarily used to support zero-copy send operations, making use of the +`NNG_MSG` special size indicator. +The value returned is a pointer to the start of the message payload buffer. + +The value of _size_ must be positive, and small enough to hold reasonable +message data plus book-keeping information. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The value of _type_ *must* be zero. +(This argument was reserved to support different kinds of memory spaces +for RDMA devices, but this was never developed in the legacy API.) + +The returned message must be disposed of by either +xref:nn_freemsg.3compat.adoc[`nn_freemsg()`] or +xref:nn_send.3compat.adoc[`nn_send()`] when the caller is finished with it. + +== RETURN VALUES + +This function returns a pointer to message buffer space, or `NULL` +on failure. + +== ERRORS + +[horizontal] +`ENOMEM`:: Insufficient memory is available. +`EINVAL`:: An invalid _size_ or _type_ was specified. +`ETERM`:: The library is shutting down. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_freemsg.3compat.adoc[nn_freemsg(3compat)], +xref:nn_reallocmsg.3compat.adoc[nn_reallocmsg(3compat)], +xref:nn_send.3compat.adoc[nn_send(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_bind - accept connections from remote peers (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include <nanomsg/nn.h> + +int nn_bind(int sock, const char *url) +---- + +== DESCRIPTION + +The `nn_bind()` function arranges for the socket _sock_ to +accept connections at the address specified by _url_. +An identifier for this socket's association with the _url_ is +returned to the caller on success. +This identfier can be used with +xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to +remove the association later. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +NOTE: The bind operation is performed asynchronously, and may not have +completed before this function returns control to the caller. + +IMPORTANT: Only transports supported by legacy _libnanomsg_ may be +used with this function. +In particular, only the schemes `tcp://`, `ipc://`, `inproc://`, and `ws://` are +supported with this function. +(Use the xref:libnng.3.adoc[modern API] to use other schemes.) + +== RETURN VALUES + +This function returns a positive identifier on success, and -1 on error. + +== ERRORS + +[horizontal] +`EADDRINUSE`:: The address specified by _url_ is already in use. +`EADDRNOTAVAIL`:: The address specified by _url_ is not available. +`EBADF`:: The socket _sock_ is not open. +`EINVAL`:: An invalid _url_ was supplied. + +== SEE ALSO + +[.text-left] +xref:nn_connect.3compat.adoc[nn_connect(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_shutdown.3compat.adoc[nn_shutdown(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_close - close socket (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +int nn_close(int sock); +---- + +== DESCRIPTION + +The `nn_close()` function closes the socket _sock_. +Any operations that are currently in progress will be terminated, and will +fail with error `EBADF`. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +== RETURN VALUES + +This function returns zero on success, and -1 on failure. + +== ERRORS + +[horizontal] +`EBADF`:: The socket is not open. +`ETERM`:: The library is shutting down. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_cmsg - message control data (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +struct nn_cmsghdr { + size_t cmsg_len; + int cmsg_level; + int cmsg_type; +}; +---- + +== DESCRIPTION + +The `nn_cmsghdr` structure describes a block of control data that is +associated with a message either sent by xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`] +or received by xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]. + +NOTE: This structure and supporting macros are provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +Each header is followed by `cmsg_len` bytes of data, plus any padding required +to align the structure. + +The only defined ancillary data at this time is the protocol headers used by +the protocols. +This uses `cmsg_level` set to `PROTO_SP` and the `cmsg_type` set to +`SP_HDR`. +The actual data for this will vary from depending on the protocol used. + +Convenience macros are provided to make working with these fields easier. + +`struct nn_cmsghdr *NN_CMSG_FIRSTHDR(struct nn_msghdr *__hdr__)`:: +This macro returns the first `struct nn_cmsghdr` header in _hdr_. + +`struct nn_cmsghdr *NN_CMSG_NXTHDR(struct nn_msghdr *__hdr__, struct nn_cmsghdr *__ch__)`:: +This macro returns a pointer to the next `struct nn_cmsghdr` in _hdr_ after _ch_. + +`void *NN_CMSG_DATA(struct nn_cmsghdr *__ch__)`:: +This macro returns a pointer to the header-specific data for _ch_. + +`size_t NN_CMSG_ALIGN(size_t __len__)`:: +This macro returns the length specified by _len_, plus any padding required to +provide the necessary alignment for another structure. + +`size_t NN_CMSG_SPACE(size_t __len__)`:: +This macro returns the amount of space required for a header, with _len_ +bytes of following data, and any necessary padding. + +`size_t NN_CMSG_LEN(size_t __len__)`:: +This macro evaluates to the length of the header (including alignment), +and the associated data of length _len_, but without any trailing padding +to align for another header. + +== SEE ALSO + +[.text-left] +xref:nn_recvmsg.3compat.adoc[nn_recvmsg(3compat)], +xref:nn_sendmsg.3compat.adoc[nn_sendmsg(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_connect - connect to remote peer (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include <nanomsg/nn.h> + +int nn_connect(int sock, const char *url) +---- + +== DESCRIPTION + +The `nn_connect()` function arranges for the socket _sock_ to +initiate connection to a peer at the address specified by _url_. +An identifier for this socket's association with the _url_ is +returned to the caller on success. +This identifier can be used with +xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to +remove the association later. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +NOTE: The connect operation is performed asynchronously, and may not have +completed before this function returns control to the caller. + +IMPORTANT: Only transports supported by legacy _libnanomsg_ may be +used with this function. +In particular, only the schemes `tcp://`, `ipc://`, `inproc://`, and `ws://` are +supported with this function. +(Use the xref:libnng.3.adoc[modern API] to use other schemes.) + +== RETURN VALUES + +This function returns a positive identifier success, and -1 on error. + +== ERRORS + +[horizontal] +`ECONNREFUSED`:: The connection attempt was refused. +`EBADF`:: The socket _sock_ is not open. +`EINVAL`:: An invalid _url_ was supplied. + +== SEE ALSO + +[.text-left] +xref:nn_bind.3compat.adoc[nn_bind(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_shutdown.3compat.adoc[nn_shutdown(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_device - create forwarding device (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +int nn_device(int sock1, int sock2); +---- + +== DESCRIPTION + +The `nn_device()` function is used to create a forwarder, where messages +received on one of the two sockets _sock1_ and _sock2_ are forwarded to +the other. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The two sockets must be compatible, and must be +xref:nng.7.adoc#raw_mode[raw mode] +sockets. +More detail about devices and how they can be used is available in the +new style xref:nng_device.3.adoc[nng_device()] documentation. + +== RETURN VALUES + +This function blocks forever, and will return -1 only when +one of the sockets is closed or an error occurs. + +== ERRORS + +[horizontal] +`EBADF`:: One of the two sockets is invalid or not open, or has +`EINVAL`:: The sockets are not compatible with each other, or not both raw. +`ENOMEM`:: Insufficient memory is available. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_errno - return most recent error (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +int nn_errno(void); +---- + +== DESCRIPTION + +The `nn_errno()` function returns the error number corresponding to the +most recent failed operation by the calling thread. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +IMPORTANT: The error numbers returned from this function may include +errors caused by system functions, which overlap the usual `errno` variable, +and this function simply returns the value of `errno`. +However, the values returned may include numeric values that are not +defined by the system, but are unique to _libnanomsg_, such as `EFSM`. + +This library implements the following error numbers, in addition to any others +that might be set for `errno` by the underlying system: + + +== RETURN VALUES + +This function returns the value of `errno`. +If no operation has failed, then this will be zero. + +== ERRORS + +[horizontal] +`EINTR`:: Operation interrupted. +`ENOMEM`:: Insufficient memory. +`EINVAL`:: Invalid argument. +`EBUSY`:: Resource is busy. +`ETIMEDOUT`:: Operation timed out. +`ECONNREFUSED`:: Connection refused by peer. +`EBADF`:: Invalid or closed socket. +`EAGAIN`:: Operation would block. +`ENOTSUP`:: Protocol or option not supported. +`EADDRINUSE`:: Requested address is already in use. +`EFSM`:: Protocol state incorrect. +`EPROTO`:: Protocol error. +`EHOSTUNREACH`:: Remote peer is unreachable. +`EADDRNOTAVAIL`:: Requested address is not available. +`EACCES`:: Permission denied. +`EMSGSIZE`:: Message is too large. +`ECONNABORTED`:: Connection attempt aborted. +`ECONNRESET`:: Connection reset by peer. +`EEXIST`:: Resource already exists. +`EMFILE`:: Too many open files. +`ENOSPC`:: Insufficient persistent storage. + +== SEE ALSO + +[.text-left] +xref:nn_strerror.3compat.adoc[nn_strerror(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_freemsg - free message (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +int nn_freemsg(void *msg); +---- + +== DESCRIPTION + +The `nn_freemsg()` deallocates a message previously allocated with +xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`] or similar functions. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +== RETURN VALUES + +This function always returns 0. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nn_allocmsg.3compat.adoc[nn_allocmsg(3compat)], +xref:nn_freemsg.3compat.adoc[nn_freemsg(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_get_statistic - get statistic (stub) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +uint64_t nn_get_statistic(int sock, int stat); +---- + +== DESCRIPTION + +The `nn_get_statistic()` function exists only as a stub, and always returns +zero. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +== RETURN VALUES + +Zero. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_getsockopt - get socket option (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +int nn_getsockopt(int sock, int level, int option, void *val, size_t *szp); +---- + +== DESCRIPTION + +The `nn_getsockopt()` function gets a socket option on socket _sock_. +The option retrieved is determined by the _level_ and _option_. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The value pointed to by _szp_ must be initialized to the size of the buffer +pointed to by _val_. +No more than this many bytes of the option will be copied into the destination +buffer on success. +On success, the value pointed to by _szp_ will be updated with the actual +size of the option. + +TIP: To determine the size to receive an option, first call this function +with _val_ set to `NULL` and the value addressed by _szp_ initialized to zero. + +The _level_ determines whether the option is a generic socket option, +or is transport-specific. +The values possible for level are as follows: + +[horizontal] +`NN_SOL_SOCKET`:: Generic socket option +`NN_IPC`:: Transport specific option for IPC. +`NN_TCP`:: Transport specific option for TCP. +`NN_WS`:: Transport specific option for WebSocket. + +The following generic socket options are possible (all are of type `int` and +thus size 4, unless otherwise indicated.) + +`NN_SNDBUF`:: +Send buffer size in bytes. + +NOTE: In _NNG_ buffers are sized as a count of messages rather than +bytes; accordingly this value is the queue depth multiplied by 1024 +(representing an estimate that the average message size is 1kB). +Applications that have unusual message sizes may wish to adjust the value +used here accordingly. + +`NN_RCVBUF`:: +Receive buffer size in bytes. + +NOTE: The same caveats for `NN_SNDBUF` apply here as well. + +`NN_SNDTIMEO`:: +Send time-out in milliseconds. +Send operations will fail with `ETIMEDOUT` if no message can be received +after this many milliseconds have transpired since the operation was started. +A value of -1 means that no timeout is applied. + +`NN_RCVTIMEO`:: +Receive time-out in milliseconds. +Receive operations will fail with `ETIMEDOUT` if no message can be received +after this many milliseconds have transpired since the operation was started. +A value of -1 means that no timeout is applied. + +`NN_RCVMAXSIZE`:: +Maximum receive size in bytes. +The socket will discard messages larger than this on receive. +The default, 1MB, is intended to prevent denial-of-service attacks. +The value -1 removes any limit. + +`NN_RECONNECT_IVL`:: +Reconnect interval in milliseconds. +After an outgoing connection is closed or fails, the socket will +automatically attempt to reconnect after this many milliseconds. +This is the starting value for the time, and is used in the first +reconnection attempt after a successful connection is made. +The default is 100. + +`NN_RECONNECT_IVL_MAX`:: +Maximum reconnect interval in milliseconds. +Subsequent reconnection attempts after a failed attempt are made at +exponentially increasing intervals (back-off), but the interval is +capped by this value. +If this value is smaller than `NN_RECONNECT_IVL`, then no exponential +back-off is performed, and each reconnect interval will be determined +solely by `NN_RECONNECT_IVL`. +The default is zero. + +`NN_LINGER`:: +This option is always zero and exists only for compatibility. + +NOTE: This option was unreliable in early releases of _libnanomsg_, and +is unsupported in _NNG_ and recent _libnanomsg_ releases. +Applications needing assurance of message delivery should either include an +explicit notification (automatic with the `NN_REQ` protocol) or allow +sufficient time for the socket to drain before closing the socket or exiting. + + +`NN_SNDPRIO`:: +This option is not implemented at this time. + +`NN_RCVPRIO`:: +This option is not implemented at this time. + +`NN_IPV4ONLY`:: +This option is not implemented at this time. + +`NN_SOCKET_NAME`:: +This option is a string, and represents the socket name. +It can be changed to help with identifying different sockets with +their different application-specific purposes. + +`NN_MAXTTL`:: +Maximum number of times a message may traverse devices or proxies. +This value, if positive, provides some protection against forwarding loops in +xref:nng_device.3.adoc[device] chains. + +NOTE: Not all protocols offer this protection, so care should still be used +in configuring device forwarding. + +`NN_DOMAIN`:: +This option of type `int` represents either the value `AF_SP` or `AF_SP_RAW`, +corresponding to the value that the socket was created with. + +`NN_PROTOCOL`:: +This option option of type `int` contains the numeric protocol number +that the socket is used with. + +`NN_RCVFD`:: +This option returns a file descriptor suitable for use in with `poll()` or +`select()` (or other system-specific polling functions). +This descriptor will be readable when a message is available for receiving +at the socket. +This option is of type `int` on all systems except Windows, where it is of +type `SOCKET`. + +NOTE: The file descriptor should not be read or written by the application, +and is not the same as any underlying descriptor used for network sockets. + +`NN_SNDFD`:: +This option returns a file descriptor suitable for use in with `poll()` or +`select()` (or other system-specific polling functions). +This descriptor will be readable when the socket is able to accept a message +for sending. +This option is of type `int` on all systems except Windows, where it is of +type `SOCKET`. + +NOTE: The file descriptor should not be read or written by the application, +and is not the same as any underlying descriptor used for network sockets. +Furthermore, the file descriptor should only be polled for _readability_. + +The following option is available for `NN_REQ` sockets +using the `NN_REQ` level: + +`NN_REQ_RESEND_IVL`:: +Request retry interval in milliseconds. +If an `NN_REQ` socket does not receive a reply to a request within this +period of time, the socket will automatically resend the request. +The default value is 60000 (one minute). + +The following option is available for `NN_SURVEYOR` sockets +using the `NN_SURVEYOR` level: + +`NN_SURVEYOR_DEADLINE`:: +Survey deadline in milliseconds for `NN_SURVEYOR` sockets. +After sending a survey message, the socket will only accept responses +from respondents for this long. +Any responses arriving after this expires are silently discarded. + +In addition, the following transport specific options are offered: + +`NN_IPC_SEC_ATTR`:: +This `NN_IPC` option is not supported at this time. + +`NN_IPC_OUTBUFSZ`:: +This `NN_IPC` option is not supported at this time. + +`NN_IPC_INBUFSZE`:: +This `NN_IPC` option is not supported at this time. + +`NN_TCP_NODELAY`:: +This `NN_TCP` option is not supported at this time. + +`NN_WS_MSG_TYPE`:: +This `NN_WS` option is not supported, as _NNG_ only supports binary messages +in this implementation. + +== RETURN VALUES + +This function returns zero on success, and -1 on failure. + +== ERRORS + +[horizontal] +`EBADF`:: The socket _sock_ is not an open socket. +`ENOMEM`:: Insufficient memory is available. +`ENOPROTOOPT`:: The level and/or option is invalid. +`EINVAL`:: The option, or the value passed, is invalid. +`ETERM`:: The library is shutting down. +`EACCES`:: The option cannot be changed. + +== SEE ALSO + +[.text-left] +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nn_close.3compat.adoc[nn_close(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_getsockopt.3compat.adoc[nn_getsockopt(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_poll - poll sockets (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include <nanomsg/nn.h> + +#define NN_POLLIN 1 +#define NN_POLLOUT 2 + +struct nn_pollfd { + int fd; + uint16_t events; + uint16_t revents; +}; + +int nn_poll(struct nn_pollfd *pfds, int npfd, int timeout); +---- + +== DESCRIPTION + +The `nn_poll()` function polls a group of sockets for readiness to send or receive. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The array of _nfds_ sockets to poll for are passed into _pfds_. +Each member of this array is initialized with the `fd` field set to +the socket, and the `events` field set to a mask that can contain either or both +of the flags `NN_POLLIN` and `NN_POLLOUT`. + +The flag `NN_POLLIN` indicates that a socket is ready for receiving without +blocking (a message is available on the socket), and the flag `NN_POLLOUT` +indicates that a socket is ready for sending without blocking. + +Upon success, the function returns the number of updates the `revents` +field of each member of the _pfds_ array, setting it to indicate +whether the requested status is true or not. + +NOTE: The `revents` field will only have a flag set if the corresponding +flag was also set in the `events` field. + +If the _timeout_ field is positive, then this function will wait for +up the that many milliseconds. +If none of the requested events occurs before that timeout occurs, then +the function will return -1 and set the error to `ETIMEDOUT`. + +If the _timeout_ is zero, then this function will return immediately, +after updating the current status of the sockets. + +If the _timeout_ is -1, then the function waits forever, or until one of the +requested events occurs. + +IMPORTANT: This function is only suitable for use with sockets obtained with the +xref:nn_socket.3compat.adoc[`nn_socket()`] function, and is not compatible +with file descriptors obtained via any other means. +This includes file descriptors obtained using the `NN_SNDFD` or `NN_RCVFD` +options with xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`] + +NOTE: This function is significantly less efficient than other polling +or asynchronous I/O mechanisms, and is provided for API compatibility only. +It's use is discouraged. + +NOTE: This function is *not* supported on systems other than POSIX derived +platforms and Windows. + +== RETURN VALUES + +This function returns the number of sockets with events on success, or -1 on error. + +== ERRORS + +[horizontal] +`ENOMEM`:: Insufficient memory available. +`EBADF`:: One of the sockets is not open. +`ETIMEDOUT`:: Operation timed out. +`ENOTSUP`:: This function is not supported on this platform. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_recv.3compat.adoc[nn_recv(3compat)], +xref:nn_send.3compat.adoc[nn_send(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_reallocmsg - reallocate message (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +void *nn_reallocmsg(void *old, size_t size); +---- + +== DESCRIPTION + +The `nn_reallocmsg()` reallocates the message _old_, making it of size _size_. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +On success, the contents of _old_ are copied into the new message +(truncating if appropriate), then _old_ is deallocated, and a pointer +to the new message payload is returned. + +On failure, the _old_ message is unchanged, and the value `NULL` is returned +to the caller. + +== RETURN VALUES + +This function returns a pointer to message buffer space, or `NULL` +on failure. + +== ERRORS + +[horizontal] +`ENOMEM`:: Insufficient memory is available. +`EINVAL`:: An invalid _size_ was specified. +`ETERM`:: The library is shutting down. + +== SEE ALSO + +[.text-left] +xref:nn_allocmsg.3compat.adoc[nn_allocmsg(3compat)], +xref:nn_freemsg.3compat.adoc[nn_freemsg(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_recv - receive data (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include <nanomsg/nn.h> + +int nn_recv(int sock, void *data, size_t size, int flags) +---- + +== DESCRIPTION + +The `nn_recv()` function receives a message from the socket _sock_. +The message body must fit within _size_ bytes, and will be stored +at the location specified by _data_, unless _size_ is the +special value `NN_MSG`, indicating a zero-copy operation. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +If _size_ has the special value `NN_MSG`, then a zero-copy operation +is performed. +In this case, instead of copying the message data into the address +specified by _data_, a new message large enough to hold the message data +will be allocated (as if by the +function xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]), and the message +payload will be stored accordingly. +In this case, the value stored at _data_ will not be message data, +but a pointer to the message itself. +In this case, on success, the caller shall take responsibility for +the final disposition of the message (such as by sending it to +another peer using xref:nn_send.3compat.adoc[`nn_send()`]) or +xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]. + +The _flags_ field may contain the special flag `NN_DONTWAIT`. +In this case, if the no message is available for immediate receipt, +the operation shall not block, but instead will fail with the error `EAGAIN`. + +== RETURN VALUES + +This function returns the number of bytes sent on success, and -1 on error. + +== ERRORS + +[horizontal] +`EAGAIN`:: The operation would block. +`EBADF`:: The socket _sock_ is not open. +`EFSM`:: The socket cannot receive in this state. +`ENOTSUP`:: This protocol cannot receive. +`ETIMEDOUT`:: Operation timed out. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_recvmsg.3compat.adoc[nn_recvmsg(3compat)], +xref:nn_send.3compat.adoc[nn_send(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_recvmsg - receive message (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include <nanomsg/nn.h> + +int nn_recvmsg(int sock, struct nn_msghdr *hdr, int flags); +---- + +== DESCRIPTION + +The `nn_recvmsg()` function receives a message into the header described by +_hdr_ using the socket _sock_. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The _flags_ field may contain the special flag `NN_DONTWAIT`. +In this case, if no message is ready for receiving on _sock_, +the operation shall not block, but instead will fail with the error `EAGAIN`. + +The _hdr_ points to a structure of type `struct nn_msghdr`, which has the +following definition: + +[source, c] +---- +struct nn_iovec { + void * iov_base; + size_t iov_len; +}; + +struct nn_msghdr { + struct nn_iovec *msg_iov; + int msg_iovlen; + void * msg_control; + size_t msg_controllen; +}; +---- + +The `msg_iov` is an array of scatter items, permitting the message +to be spread into different memory blocks. +There are `msg_iovlen` elements in this array, each of which +has the base address (`iov_base`) and length (`iov_len`) indicated. + +The last member of this array may have the `iov_len` field set to `NN_MSG`, +in which case the function shall allocate a message buffer, and store the +pointer to it at the address indicated by `iov_base`. +This can help save an extra copy operation. +The buffer should be deallocated by xref:nn_freemsg.3compat.adoc[`nn_freemsg()`] +or similar when it is no longer needed. + +The values of `msg_control` and `msg_controllen` describe a buffer +of ancillary data associated with the message. +This is currently only useful to obtain the message headers +used with xref:nng.7.adoc#raw_mode[raw mode] sockets. +In all other circumstances these fields should be zero. +Details about this structure are covered in +xref:nn_cmsg.3compat.adoc[`nn_cmsg(3compat)`]. + +== RETURN VALUES + +This function returns the number of bytes received on success, and -1 on error. + +== ERRORS + +[horizontal] +`EAGAIN`:: The operation would block. +`EBADF`:: The socket _sock_ is not open. +`EFSM`:: The socket cannot receive in this state. +`EINVAL`:: The _hdr_ is invalid. +`ENOTSUP`:: This protocol cannot receive. +`ETIMEDOUT`:: Operation timed out. + +== SEE ALSO + +[.text-left] +xref:nn_cmsg.3compat.adoc[nn_cmsg(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_recv.3compat.adoc[nn_recv(3compat)], +xref:nn_send.3compat.adoc[nn_send(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_send - send data (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include <nanomsg/nn.h> + +int nn_send(int sock, const void *data, size_t size, int flags) +---- + +== DESCRIPTION + +The `nn_send()` function creates a message containing _data_ (of size _size_), +and sends using the socket _sock_. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +If _size_ has the special value `NN_MSG`, then a zero-copy operation +is performed. +In this case, _data_ points not to the message content itself, but instead +is a pointer to the pointer, an extra level of pointer indirection. +The message must have been previously allocated by +xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`] or +xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]`, using the same `NN_MSG` size. +In this case, the ownership of the message shall remain with +the caller, unless the function returns 0, indicating that the +function has taken responsibility for delivering or disposing of the +message. + +The _flags_ field may contain the special flag `NN_DONTWAIT`. +In this case, if the socket is unable to accept more data for sending, +the operation shall not block, but instead will fail with the error `EAGAIN`. + +NOTE: The send operation is performed asynchronously, and may not have +completed before this function returns control to the caller. + +== RETURN VALUES + +This function returns the number of bytes sent on success, and -1 on error. + +== ERRORS + +[horizontal] +`EAGAIN`:: The operation would block. +`EBADF`:: The socket _sock_ is not open. +`EFSM`:: The socket cannot send in this state. +`ENOTSUP`:: This protocol cannot send. +`ETIMEDOUT`:: Operation timed out. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_recv.3compat.adoc[nn_recv(3compat)], +xref:nn_sendmsg.3compat.adoc[nn_sendmsg(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_sendmsg - send message (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include <nanomsg/nn.h> + +int nn_sendmsg(int sock, const struct nn_msghdr *hdr, int flags); +---- + +== DESCRIPTION + +The `nn_sendmsg()` function sends the message described by _hdr_ using the +socket _sock_. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The _flags_ field may contain the special flag `NN_DONTWAIT`. +In this case, if the socket is unable to accept more data for sending, +the operation shall not block, but instead will fail with the error `EAGAIN`. + +The _hdr_ points to a structure of type `struct nn_msghdr`, which has the +following definition: + +[source, c] +---- +struct nn_iovec { + void * iov_base; + size_t iov_len; +}; + +struct nn_msghdr { + struct nn_iovec *msg_iov; + int msg_iovlen; + void * msg_control; + size_t msg_controllen; +}; +---- + +The `msg_iov` is an array of gather items, permitting the message +to be spread into different memory blocks. +There are `msg_iovlen` elements in this array, each of which +has the base address (`iov_base`) and length (`iov_len`) indicated. + +For buffers allocated for zero copy +(such as by xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]), the value +of `iov_base` should be the address of the pointer to the buffer, +rather than the address of the buffer itself. +In this case, the value of `iov_len` should be `NN_MSG`, +as the length is inferred from the allocated message. +If the `msg_iovlen` field is `NN_MSG`, then this function will free +the associated buffer after it is done with it, if it returns successfully. +(If the function returns with an error, then the caller retains ownership +of the associated buffer and may retry the operation or free the buffer +at its choice.) + +The values of `msg_control` and `msg_controllen` describe a buffer +of ancillary data to send the message. +This is currently only useful to provide the message headers +used with xref:nng.7.adoc#raw_mode[raw mode] sockets. +In all other circumstances these fields should be zero. +Details about this structure are covered in +xref:nn_cmsg.3compat.adoc[`nn_cmsg(3compat)`]. + +NOTE: The send operation is performed asynchronously, and may not have +completed before this function returns control to the caller. + +== RETURN VALUES + +This function returns the number of bytes sent on success, and -1 on error. + +== ERRORS + +[horizontal] +`EAGAIN`:: The operation would block. +`EBADF`:: The socket _sock_ is not open. +`EFSM`:: The socket cannot send in this state. +`EINVAL`:: The _hdr_ is invalid. +`ENOTSUP`:: This protocol cannot send. +`ETIMEDOUT`:: Operation timed out. + +== SEE ALSO + +[.text-left] +xref:nn_cmsg.3compat.adoc[nn_cmsg(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_recv.3compat.adoc[nn_recv(3compat)], +xref:nn_send.3compat.adoc[nn_send(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_setsockopt - set socket option (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +int nn_setsockopt(int sock, int level, int option, const void *val, size_t sz); +---- + +== DESCRIPTION + +The `nn_setsockopt()` function sets a socket option on socket _sock_, +affecting the behavior of the socket. +The option set is determined by the _level_ and _option_. +The value of the option is set by _val_, and _sz_, which are pointers to +the actual value and the size of the value, respectively. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +The _level_ determines whether the option is a generic socket option, +or is transport-specific. +The values possible for level are as follows: + +[horizontal] +`NN_SOL_SOCKET`:: Generic socket option +`NN_IPC`:: Transport specific option for IPC. +`NN_TCP`:: Transport specific option for TCP. +`NN_WS`:: Transport specific option for WebSocket. + +The following generic socket options are possible (all are of type `int` and +thus size 4, unless otherwise indicated.) + +`NN_SNDBUF`:: +Send buffer size in bytes. + +NOTE: In _NNG_ buffers are sized as a count of messages rather than +bytes, and so an attempt to estimate a conversion based upon a predetermined +message size of 1kB is made. +The value supplied is rounded up to the nearest value divisible by 1024, and +then divided by 1024 to convert to a message count. +Applications that have unusual message sizes may wish to adjust the value +used here accordingly. + +`NN_RCVBUF`:: +Receive buffer size in bytes. + +NOTE: The same caveats for `NN_SNDBUF` apply here as well. + +`NN_SNDTIMEO`:: +Send time-out in milliseconds. +Send operations will fail with `ETIMEDOUT` if no message can be received +after this many milliseconds have transpired since the operation was started. +A value of -1 means that no timeout is applied. + +`NN_RCVTIMEO`:: +Receive time-out in milliseconds. +Receive operations will fail with `ETIMEDOUT` if no message can be received +after this many milliseconds have transpired since the operation was started. +A value of -1 means that no timeout is applied. + +`NN_RCVMAXSIZE`:: +Maximum receive size in bytes. +The socket will discard messages larger than this on receive. +The default, 1MB, is intended to prevent denial-of-service attacks. +The value -1 removes any limit. + +`NN_RECONNECT_IVL`:: +Reconnect interval in milliseconds. +After an outgoing connection is closed or fails, the socket will +automatically attempt to reconnect after this many milliseconds. +This is the starting value for the time, and is used in the first +reconnection attempt after a successful connection is made. +The default is 100. + +`NN_RECONNECT_IVL_MAX`:: +Maximum reconnect interval in milliseconds. +Subsequent reconnection attempts after a failed attempt are made at +exponentially increasing intervals (back-off), but the interval is +capped by this value. +If this value is smaller than `NN_RECONNECT_IVL`, then no exponential +back-off is performed, and each reconnect interval will be determined +solely by `NN_RECONNECT_IVL`. +The default is zero. + +`NN_LINGER`:: +This option is ignored, and exists only for compatibility. + +NOTE: This option was unreliable in early releases of _libnanomsg_, and +is unsupported in _NNG_ and recent _libnanomsg_ releases. +Applications needing assurance of message delivery should either include an +explicit notification (automatic with the `NN_REQ` protocol) or allow +sufficient time for the socket to drain before closing the socket or exiting. + +`NN_SNDPRIO`:: +This option is not implemented at this time. + +`NN_RCVPRIO`:: +This option is not implemented at this time. + +`NN_IPV4ONLY`:: +This option is not implemented at this time. + +`NN_SOCKET_NAME`:: +This option is a string, and represents the socket name. +It can be changed to help with identifying different sockets with +their different application-specific purposes. + +`NN_MAXTTL`:: +Maximum number of times a message may traverse devices or proxies. +This value, if positive, provides some protection against forwarding loops in +xref:nng_device.3.adoc[device] chains. + +NOTE: Not all protocols offer this protection, so care should still be used +in configuring device forwarding. + +The following option is available for `NN_REQ` sockets +using the `NN_REQ` level: + +`NN_REQ_RESEND_IVL`:: +Request retry interval in milliseconds. +If an `NN_REQ` socket does not receive a reply to a request within this +period of time, the socket will automatically resend the request. +The default value is 60000 (one minute). + +The following options are available for `NN_SUB` sockets using the `NN_SUB` level: + +`NN_SUB_SUBSCRIBE`:: +Subscription topic, for `NN_SUB` sockets. +This sets a subscription topic. +When a message from a publisher arrives, it is compared against all +subscriptions. +If the first _sz_ bytes of the message are not identical to _val_, +then the message is silently discarded. + +TIP: To receive all messages, subscribe to an empty topic (_sz_ equal to zero). + +`NN_SUB_UNSUBSCRIBE`:: +Removes a subscription topic that was earlier established. + +The following option is available for `NN_SURVEYOR` sockets +using the `NN_SURVEYOR` level: + +`NN_SURVEYOR_DEADLINE`:: +Survey deadline in milliseconds for `NN_SURVEYOR` sockets. +After sending a survey message, the socket will only accept responses +from respondents for this long. +Any responses arriving after this expires are silently discarded. + +In addition, the following transport specific options are offered: + +`NN_IPC_SEC_ATTR`:: +This `NN_IPC` option is not supported at this time. + +`NN_IPC_OUTBUFSZ`:: +This `NN_IPC` option is not supported at this time. + +`NN_IPC_INBUFSZE`:: +This `NN_IPC` option is not supported at this time. + +`NN_TCP_NODELAY`:: +This `NN_TCP` option is not supported at this time. + +`NN_WS_MSG_TYPE`:: +This `NN_WS` option is not supported at this time. + +== RETURN VALUES + +This function returns zero on success, and -1 on failure. + +== ERRORS + +[horizontal] +`EBADF`:: The socket _sock_ is not an open socket. +`ENOMEM`:: Insufficient memory is available. +`ENOPROTOOPT`:: The level and/or option is invalid. +`EINVAL`:: The option, or the value passed, is invalid. +`ETERM`:: The library is shutting down. +`EACCES`:: The option cannot be changed. + +== SEE ALSO + +[.text-left] +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nn_close.3compat.adoc[nn_close(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_getsockopt.3compat.adoc[nn_getsockopt(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_shutdown - shut down endpoint (compatible API) + +== SYNOPSIS + +[source, c] +---- +#include <nanomsg/nn.h> + +int nn_shutdown(int sock, int ep) +---- + +== DESCRIPTION + +The `nn_shutdown()` shuts down the endpoint _ep_, which is either a listener or +a dialer) on the socket _sock_. +This will stop the socket from either accepting new connections, or establishing +old ones. +Additionally, any established connections associated with _ep_ will be closed. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +== RETURN VALUES + +This function returns zero on success, and -1 on error. + +== ERRORS + +[horizontal] +`EBADF`:: The socket _sock_ is not open. +`EINVAL`:: An invalid _ep_ was supplied. + +== SEE ALSO + +[.text-left] +xref:nn_bind.3compat.adoc[nn_bind(3compat)], +xref:nn_connect.3compat.adoc[nn_connect(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nn_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_socket - create socket (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +int nn_socket(int af, int proto); +---- + +== DESCRIPTION + +The `nn_socket()` function creates socket using the address family _af_ and +protocol _proto_ and returns it. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +IMPORTANT: Mixing the compatibility API and the modern API is not supported +on a given socket. + +NOTE: Some protocols, transports, and features are only available in the modern API. + +The address family _af_ can be one of two values: + +[horizontal] +`AF_SP`:: Normal socket. +`AF_SP_RAW`:: xref:nng.7.adoc#raw_mode[Raw mode] socket. + +The protocol indicates the protocol to be used when creating the socket. +The following protocols are defined: + +[horizontal] +`NN_PAIR`:: xref:nng_pair.7.adoc[Pair] protocol. +`NN_PUB`:: xref:nng_pub.7.adoc[Publisher] protocol. +`NN_SUB`:: xref:nng_sub.7.adoc[Subscriber] protocol. +`NN_REQ`:: xref:nng_req.7.adoc[Requestor] protocol. +`NN_REP`:: xref:nng_rep.7.adoc[Replier] protocol. +`NN_PUSH`:: xref:nng_push.7.adoc[Push] protocol. +`NN_PULL`:: xref:nng_pull.7.adoc[Pull] protocol. +`NN_SURVEYOR`:: xref:nng_surveyor.7.adoc[Surveyor] protocol. +`NN_RESPONDENT`:: xref:nng_respondent.7.adoc[Respondent] protocol. +`NN_BUS`:: xref:nng_bus.7.adoc[Bus] protocol. + +== RETURN VALUES + +This function returns a valid socket number on success, and -1 on failure. + +== ERRORS + +[horizontal] +`ENOMEM`:: Insufficient memory is available. +`ENOTSUP`:: The protocol is not supported. +`ETERM`:: The library is shutting down. + +== SEE ALSO + +[.text-left] +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nn_close.3compat.adoc[nn_close(3compat)], +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_strerror - return message for error (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +const char *nn_strerror(int err); +---- + +== DESCRIPTION + +The `nn_strerror()` function returns a human readable message corresponding +to the given error number _err_. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +== RETURN VALUES + +This function returns the message corresponding to _err_. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nn_term - terminate library (compatible API) + +== SYNOPSIS + +[source,c] +---- +#include <nanomsg/nn.h> + +void nn_term(void); +---- + +== DESCRIPTION + +The `nn_term()` function closes any open sockets, and frees all resources +allocated by the library. +Any operations that are currently in progress will be terminated, and will +fail with error `EBADF` or `ETERM`. + +NOTE: This function is provided for API +xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. +Consider using the relevant xref:libnng.3.adoc[modern API] instead. + +IMPORTANT: This function is not thread-safe, and is not suitable for use +in library calls. +The intended purpose of this is to clean up at application termination; for +example by registering this function with `atexit()`. +This can help prevent false leak reports caused when memory checkers notice +global resources allocated by the library. +Libraries should never use this function, but should explicitly close their +own sockets directly. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nn_errno.3compat.adoc[nn_errno(3compat)], +xref:nn_socket.3compat.adoc[nn_socket(3compat)], +xref:nng_compat.3compat.adoc[nng_compat(3compat)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/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 <nng/nng.h> -#include <nng/protocol/reqrep0/rep.h> - -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 <nng/nng.h> +#include <nng/protocol/reqrep0/rep.h> + +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 <nng/nng.h> -#include <nng/protocol/reqrep0/req.h> - -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 <nng/nng.h> +#include <nng/protocol/reqrep0/req.h> + +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 <nng/nng.h> -#include <nng/protocol/survey0/respond.h> - -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 <nng/nng.h> +#include <nng/protocol/survey0/respond.h> + +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_. |