diff options
24 files changed, 1682 insertions, 44 deletions
diff --git a/docs/man/man3compat.desc b/docs/man/man3compat.desc index f9075ddd..a1141850 100644 --- a/docs/man/man3compat.desc +++ b/docs/man/man3compat.desc @@ -1 +1,3 @@ This section documents the _nanomsg_ 1.0 libary compatible functions. +The functions in this section not be used except to aid in transitioning +from the older _libnanomsg_ library.
\ No newline at end of file diff --git a/docs/man/nn_allocmsg.3compat.adoc b/docs/man/nn_allocmsg.3compat.adoc new file mode 100644 index 00000000..943ecf4b --- /dev/null +++ b/docs/man/nn_allocmsg.3compat.adoc @@ -0,0 +1,66 @@ += 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 ot 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 +`<<nn_freemsg.3compat#,nn_freemsg()>>` or +`<<nn_send.3compat#,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 + +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_freemsg.3compat#,nn_freemsg(3compat)>>, +<<nn_reallocmsg.3compat#,nn_reallocmsg(3compat)>>, +<<nn_send.3compat#,nn_send(3compat)>>, +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_bind.3compat.adoc b/docs/man/nn_bind.3compat.adoc new file mode 100644 index 00000000..79ff2c04 --- /dev/null +++ b/docs/man/nn_bind.3compat.adoc @@ -0,0 +1,66 @@ += nn_bind(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_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 "`endpoint identifier`" for this socket's association with the _url_ is +returned to the caller on success. +This ID can be used with `<<nn_shutdown.3compat#,nn_shutdown()>>`` to +"`unbind`" the socket from the address at _url_. + +NOTE: This function is provided for API +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 <<libnng.3#,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 + +<<nn_connect.3compat#,nn_connect(3compat)>>, +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_shutdown.3compat#,nn_shutdown(3compat)>>, +<<nn_socket.3compat#,nn_socket(3compat)>>, +<<nng_compat.3compat#,nn_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_close.3compat.adoc b/docs/man/nn_close.3compat.adoc new file mode 100644 index 00000000..40edef52 --- /dev/null +++ b/docs/man/nn_close.3compat.adoc @@ -0,0 +1,50 @@ += 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 + +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_socket.3compat#,nn_socket(3compat)>>, +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_cmsg.3compat.adoc b/docs/man/nn_cmsg.3compat.adoc new file mode 100644 index 00000000..c5347a12 --- /dev/null +++ b/docs/man/nn_cmsg.3compat.adoc @@ -0,0 +1,77 @@ += 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 `<<nn_sendmsg.3compat#,nn_sendmsg()>>` +or received by `<<nn_recvmsg.3compat#,nn_recvmsg()>>`. + +NOTE: This structure and supporting macros are provided for API +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 evalutes 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 + +<<nn_recvmsg.3compat#,nn_recvmsg(3compat)>>, +<<nn_sendmsg.3compat#,nn_sendmsg(3compat)>>, +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_connect.3compat.adoc b/docs/man/nn_connect.3compat.adoc new file mode 100644 index 00000000..add14060 --- /dev/null +++ b/docs/man/nn_connect.3compat.adoc @@ -0,0 +1,65 @@ += 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 +inititate connection to a peer at the address specified by _url_. +An "`endpoint identifier`" for this socket's association with the _url_ is +returned to the caller on success. +This ID can be used with `<<nn_shutdown.3compat#,nn_shutdown()>>`` to +"`unbind`" the socket from the address at _url_. + +NOTE: This function is provided for API +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 <<libnng.3#,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 + +<<nn_bind.3compat#,nn_bind(3compat)>>, +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_shutdown.3compat#,nn_shutdown(3compat)>>, +<<nn_socket.3compat#,nn_socket(3compat)>>, +<<nng_compat.3compat#,nn_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_device.3compat.adoc b/docs/man/nn_device.3compat.adoc new file mode 100644 index 00000000..945396dc --- /dev/null +++ b/docs/man/nn_device.3compat.adoc @@ -0,0 +1,57 @@ += 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,modern API>> instead. + +The two sockets must be compatible, and must be <<nng.7#raw_mode,raw mode>> +sockets. +More detail about devices and how they can be used is available in the +new style <<nng_device.3#,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 + +[horizonal] +`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 + +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_socket.3compat#,nn_socket(3compat)>>, +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_errno.3compat.adoc b/docs/man/nn_errno.3compat.adoc new file mode 100644 index 00000000..316a419e --- /dev/null +++ b/docs/man/nn_errno.3compat.adoc @@ -0,0 +1,78 @@ += 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 + +<<nn_strerror.3compat#,nn_strerror(3compat)>>, +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_freemsg.3compat.adoc b/docs/man/nn_freemsg.3compat.adoc new file mode 100644 index 00000000..d23d9f0a --- /dev/null +++ b/docs/man/nn_freemsg.3compat.adoc @@ -0,0 +1,48 @@ += 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 +`<<nn_allocmsg.3compat#,nn_allocmsg()>>`` or similar functions. + +NOTE: This function is provided for API +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,modern API>> instead. + +== RETURN VALUES + +This function always returns 0. + +== ERRORS + +None. + +== SEE ALSO + +<<nn_allocmsg.3compat#,nn_allocmsg(3compat)>>, +<<nn_freemsg.3compat#,nn_freemsg(3compat)>>, +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_get_statistic.3compat.adoc b/docs/man/nn_get_statistic.3compat.adoc new file mode 100644 index 00000000..a8129f8d --- /dev/null +++ b/docs/man/nn_get_statistic.3compat.adoc @@ -0,0 +1,45 @@ += 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,modern API>> instead. + +== RETURN VALUES + +Zero. + +== ERRORS + +None. + +== SEE ALSO + +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_getsockopt.3compat.adoc b/docs/man/nn_getsockopt.3compat.adoc new file mode 100644 index 00000000..73ab2dee --- /dev/null +++ b/docs/man/nn_getsockopt.3compat.adoc @@ -0,0 +1,216 @@ += 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 _nng_ 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 (backoff), but the interval is +capped by this value. +If this value is smaller than `NN_RECONNECT_IVL`, then no exponential +backoff 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 "`hops`" through proxies and devices a message may go through. +This value, if positive, provides some protection against forwarding loops in +<<nng_device.3#,device>> chains. + +NOTE: Not all protocols offer this protection, so care should still be used +in configuring device forwarding. + +`NN_DOMAIN`:: +This contains either the value `AF_SP` or `AF_SP_RAW`, corresponding +to the value that the socket was created with. + +`NN_PROTOCOL`:: +This option is not supported at this time. + +`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. + +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_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 the socket is able to accept a message +for sending. + +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_. + +`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). + +`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 + +<<nng_socket.5#,nng_socket(5)>>, +<<nn_close.3compat#,nn_close(3compat)>>, +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_getsockopt.3compat#,nn_getsockopt(3compat)>>, +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_reallocmsg.3compat.adoc b/docs/man/nn_reallocmsg.3compat.adoc new file mode 100644 index 00000000..c7a186ae --- /dev/null +++ b/docs/man/nn_reallocmsg.3compat.adoc @@ -0,0 +1,58 @@ += 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 + +<<nn_allocmsg.3compat#,nn_allocmsg(3compat)>>, +<<nn_freemsg.3compat#,nn_freemsg(3compat)>>, +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_recv.3compat.adoc b/docs/man/nn_recv.3compat.adoc new file mode 100644 index 00000000..8b873f8f --- /dev/null +++ b/docs/man/nn_recv.3compat.adoc @@ -0,0 +1,74 @@ += 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_send - 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 `<<nn_allocmsg.3compat#,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 `<<nn_send.3compat#,nn_send()>>`) or +`<<nn_freemsg.3compat#,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 + +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_recvmsg.3compat#,nn_recvmsg(3compat)>>, +<<nn_send.3compat#,nn_send(3compat)>>, +<<nn_socket.3compat#,nn_socket(3compat)>>, +<<nng_compat.3compat#,nn_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_recvmsg.3compat.adoc b/docs/man/nn_recvmsg.3compat.adoc new file mode 100644 index 00000000..f9683d50 --- /dev/null +++ b/docs/man/nn_recvmsg.3compat.adoc @@ -0,0 +1,98 @@ += 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 heade described by +_hdr_ using the socket _sock_. + +NOTE: This function is provided for API +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 `<<nn_freemsg.3compat#,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 currenly only useful to obtain the message headers +used with <<nng.7#raw_mode,raw mode>> sockets. +In all other circumstances these fields should be zero. +Details about this structure are covered in +`<<nn_cmsg.3compat#,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 + +<<nn_cmsg.3compat#,nn_cmsg(3compat)>>, +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_recv.3compat#,nn_recv(3compat)>>, +<<nn_send.3compat#,nn_send(3compat)>>, +<<nn_socket.3compat#,nn_socket(3compat)>>, +<<nng_compat.3compat#,nn_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_send.3compat.adoc b/docs/man/nn_send.3compat.adoc new file mode 100644 index 00000000..181d8c7f --- /dev/null +++ b/docs/man/nn_send.3compat.adoc @@ -0,0 +1,73 @@ += 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 +`<<nn_allocmsg.3compat#,nn_allocmsg()>>` or +`<<nn_recvmsg.3compat#,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 + +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_recv.3compat#,nn_recv(3compat)>>, +<<nn_sendmsg.3compat#,nn_sendmsg(3compat)>>, +<<nn_socket.3compat#,nn_socket(3compat)>>, +<<nng_compat.3compat#,nn_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_sendmsg.3compat.adoc b/docs/man/nn_sendmsg.3compat.adoc new file mode 100644 index 00000000..71a69c14 --- /dev/null +++ b/docs/man/nn_sendmsg.3compat.adoc @@ -0,0 +1,106 @@ += 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 `<<nn_allocmsg.3compat#,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 currenly only useful to provide the message headers +used with <<nng.7#raw_mode,raw mode>> sockets. +In all other circumstances these fields should be zero. +Details about this structure are covered in +`<<nn_cmsg.3compat#,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 + +<<nn_cmsg.3compat#,nn_cmsg(3compat)>>, +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_recv.3compat#,nn_recv(3compat)>>, +<<nn_send.3compat#,nn_send(3compat)>>, +<<nn_socket.3compat#,nn_socket(3compat)>>, +<<nng_compat.3compat#,nn_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_setsockopt.3compat.adoc b/docs/man/nn_setsockopt.3compat.adoc new file mode 100644 index 00000000..af4539b5 --- /dev/null +++ b/docs/man/nn_setsockopt.3compat.adoc @@ -0,0 +1,202 @@ += 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 rouned 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 (backoff), but the interval is +capped by this value. +If this value is smaller than `NN_RECONNECT_IVL`, then no exponential +backoff 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 "`hops`" through proxies and devices a message may go through. +This value, if positive, provides some protection against forwarding loops in +<<nng_device.3#,device>> chains. + +NOTE: Not all protocols offer this protection, so care should still be used +in configuring device forwarding. + +// NN_DOMAIN is readonly. +// NN_PROTOCOL is not supported. +// NN_RCVFD is read-only. +// NN_SNDFD is read-only. + +`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). + +`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. + +`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 + +<<nng_socket.5#,nng_socket(5)>>, +<<nn_close.3compat#,nn_close(3compat)>>, +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_getsockopt.3compat#,nn_getsockopt(3compat)>>, +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_shutdown.3compat.adoc b/docs/man/nn_shutdown.3compat.adoc new file mode 100644 index 00000000..2de6b1f0 --- /dev/null +++ b/docs/man/nn_shutdown.3compat.adoc @@ -0,0 +1,54 @@ += nn_shutdown(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_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_ 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 + +<<nn_bind.3compat#,nn_bind(3compat)>>, +<<nn_connect.3compat#,nn_connect(3compat)>>, +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_socket.3compat#,nn_socket(3compat)>>, +<<nng_compat.3compat#,nn_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_socket.3compat.adoc b/docs/man/nn_socket.3compat.adoc new file mode 100644 index 00000000..33bb1626 --- /dev/null +++ b/docs/man/nn_socket.3compat.adoc @@ -0,0 +1,77 @@ += 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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`:: <<nng.7#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`:: <<nng_pair.7#,Pair>> protocol. +`NN_PUB`:: <<nng_pub.7#,Publisher>> protocol. +`NN_SUB`:: <<nng_sub.7#,Subscriber>> protocol. +`NN_REQ`:: <<nng_req.7#,Requestor>> protocol. +`NN_REP`:: <<nng_rep.7#,Replier>> protocol. +`NN_PUSH`:: <<nng_push.7#,Push>> protocol. +`NN_PULL`:: <<nng_pull.7#,Pull>> protocol. +`NN_SURVEYOR`:: <<nng_surveyor.7#,Surveyor>> protocol. +`NN_RESPONDENT`:: <<nng_respondent.7#,Respondent>> protocol. +`NN_BUS`:: <<nng_bus.7#,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 + +<<nng_socket.5#,nng_socket(5)>>, +<<nn_close.3compat#,nn_close(3compat)>>, +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_strerror.3compat.adoc b/docs/man/nn_strerror.3compat.adoc new file mode 100644 index 00000000..090a012a --- /dev/null +++ b/docs/man/nn_strerror.3compat.adoc @@ -0,0 +1,46 @@ += 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_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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,modern API>> instead. + +== RETURN VALUES + +This function returns the message corresponding to _err_. + +== ERRORS + +None. + +== SEE ALSO + +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nn_term.3compat.adoc b/docs/man/nn_term.3compat.adoc new file mode 100644 index 00000000..e61a40ed --- /dev/null +++ b/docs/man/nn_term.3compat.adoc @@ -0,0 +1,58 @@ += 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 +<<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_. +Consider using the relevant <<libnng.3#,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 + +<<nn_errno.3compat#,nn_errno(3compat)>>, +<<nn_socket.3compat#,nn_socket(3compat)>>, +<<nng_compat.3compat#,nng_compat(3compat)>>, +<<nng.7#,nng(7)>> diff --git a/docs/man/nng_compat.3compat.adoc b/docs/man/nng_compat.3compat.adoc index a0ac64c2..5493e41f 100644 --- a/docs/man/nng_compat.3compat.adoc +++ b/docs/man/nng_compat.3compat.adoc @@ -27,9 +27,9 @@ most _nanomsg_ 1.0 applications. IMPORTANT: This is intended to faciliate converting legacy applications to use the _nng_ library. -New applications shoud not use the newer <<nng.7#,_nng_>> API instead. +New applications should use the newer <<nng.7#,_nng_>> API instead. -Applications making use of this ((compatibility layer)) take care +Applications making use of this ((compatibility layer)) must take care to link with <<libnng.3#,_libnng_>> instead of _libnn_. NOTE: Some capabilities, protocols, and transports, will not be accessible @@ -50,34 +50,59 @@ used in compilation. The following functions are provided: +// For PDF, we don't have horizontal lists, so we have to conditionalize +// this and use tables there -- it looks ugly otherwise. +ifndef::backend-pdf[] +[horizontal] +`<<nn_socket.3compat#,nn_socket()>>`:: create socket +`<<nn_getsockopt.3compat#,nn_getsockopt()>>`:: get socket option +`<<nn_setsockopt.3compat#,nn_setsockopt()>>`:: set socket option +`<<nn_bind.3compat#,nn_bind()>>`:: accept connections from remote peers +`<<nn_connect.3compat#,nn_connect()>>`:: connect to remote peer +`<<nn_send.3compat#,nn_send()>>`:: send data +`<<nn_recv.3compat#,nn_recv()>>`:: receive data +`<<nn_shutdown.3compat#,nn_shutdown()>>`:: shut down endpoint +`<<nn_close.3compat#,nn_close()>>`:: close socket +//`nn_poll()`:: poll sockets +`<<nn_device.3compat#,nn_device()>>`:: create forwarding device +`<<nn_recvmsg.3compat#,nn_recvmsg()>>`:: receive message +`<<nn_sendmsg.3compat#,nn_sendmsg()>>`:: send message +`<<nn_cmsg.3compat#,nn_cmsg()>>`:: message control data +`<<nn_get_statistic.3compat#,nn_get_statistic()>>`:: get statistic (stub) +`<<nn_allocmsg.3compat#,nn_allocmsg()>>`:: allocate message +`<<nn_reallocmsg.3compat#,nn_reallocmsg()>>`:: reallocate message +`<<nn_freemsg.3compat#,nn_freemsg()>>`:: free message +`<<nn_errno.3compat#,nn_errno()>>`:: return most recent error +`<<nn_strerror.3compat#,nn_strerror()>>`:: return message for error +`<<nn_term.3compat#,nn_term()>>`:: terminate library +endif::[] +ifdef::backend-pdf[] // Add links for the following as they are written. +[.hdlist,width=90%, grid=rows,cols="1,2", align="center"] |=== -|`nn_socket()`|create a socket -|`nn_getsockopt()`|get socket option -|`nn_setsockopt()`|set socket option -|`nn_bind()`|accept connections from remote peers -|`nn_connect()`|connect to remote peer -|`nn_send()`|send data -|`nn_recv()`|receive data -|`nn_shutdown()`|shut down endpoint -|`nn_close()`|close socket -|`nn_poll()`|poll sockets -|`nn_device()`|create forwarding device -|`nn_recvmsg()`|receive message -|`nn_sendmsg()`|send message -|`nn_get_statistic()`|get statistic (stub) -|`nn_allocmsg()`|allocate message -|`nn_reallocmsg()`|reallocate message -|`nn_freemsg()`|free message -|`nn_errno()`|return most recent error -|`nn_strerror()`|return message for error -|`nn_term()`|terminate library +|`<<nn_socket.3compat#,nn_socket()`>>|create socket +|`<<nn_getsockopt.3compat#,nn_getsockopt()>>`|get socket option +|`<<nn_setsockopt.3compat#,nn_setsockopt()>>`|set socket option +|`<<nn_bind.3compat#,nn_bind()>>`|accept connections from remote peers +|`<<nn_connect.3compat#,nn_connect()>>`|connect to remote peer +|`<<nn_send.3compat#,nn_send()>>`|send data +|`<<nn_recv.3compat#,nn_recv()>>`|receive data +|`<<nn_shutdown.3compat#,nn_shutdown()>>`|shut down endpoint +|`<<nn_close.3compat#,nn_close()>>`|close socket +//|`nn_poll()`|poll sockets +|`<<nn_device.3compat#,nn_device()>>`|create forwarding device +|`<<nn_recvmsg.3compat#,nn_recvmsg()>>`|receive message +|`<<nn_sendmsg.3compat#,nn_sendmsg()>>`|send message +|`<<nn_cmsg.3compat#,nn_cmsg()>>`|message control data +|`<<nn_get_statistic.3compat#,nn_get_statistic()>>`|get statistic (stub) +|`<<nn_allocmsg.3compat#,nn_allocmsg()>>`|allocate message +|`<<nn_reallocmsg.3compat#,nn_reallocmsg()>>`|reallocate message +|`<<nn_freemsg.3compat#,nn_freemsg()>>`|free message +|`<<nn_errno.3compat#,nn_errno()>>`|return most recent error +|`<<nn_strerror.3compat#,nn_strerror()>>`|return message for error +|`<<nn_term.3compat#,nn_term()>>`|terminate library |=== - -NOTE: Documentation for the compatibility functions will be -supplied here later. -In the meantime it can be found online at the -http://nanomsg.org[nanomsg site]. +endif::[] There are a few caveats, that should be kept in mind. @@ -94,10 +119,8 @@ NOTE: The following options (`nn_getsockopt`) are unsupported: Some of these will probably be added back in the future when the relevant support is added to _nng_. -NOTE: Statistics (`nn_get_statistic`) are unsupported. -The plan is to support statistics in the native _nng_ API, but -we think there is no need for this in a compatibility layer. -Hence, this function returns `ENOTSUP`. +NOTE: Access to statistics using this legacy API +(`<<nn_get_statistic.3compat#,nn_get_statistic()>>`) is unsupported. NOTE: Some transports can support longer URLs than legacy _libnanomsg_ can. It is a good idea to use short pathnames in URLs if interoperability @@ -124,18 +147,7 @@ IMPORTANT: It *is* possible at present to intermix sockets between the new and the old APIs, but this is not a guaranteed feature, and should only be used temporarily to facilitate transitioning code to the new APIs. -// === Common Functions -// -// The following common functions exist in _libnng_. -// -// |=== -// |<<nng_alloc.3#,nng_alloc()>>|allocate memory -// |<<nng_free.3#,nng_free()>>|free memory -// |<<nng_strerror.3#,nng_strerror()>>|return an error description -// |<<nng_version.3#,nng_version()>>|report library version -// |=== -// - == SEE ALSO +<<libnng.3#,libnng(3)>>, <<nng.7#,nng(7)>> diff --git a/docs/man/nng_device.3.adoc b/docs/man/nng_device.3.adoc index 09717e21..aaf71af6 100644 --- a/docs/man/nng_device.3.adoc +++ b/docs/man/nng_device.3.adoc @@ -97,7 +97,8 @@ the requestor, if reliable delivery is needed. == RETURN VALUES -This function returns 0 on success, and non-zero otherwise. +This function continues running, and only returns an appropriate error when +one occurs, or if one of the sockets is closed. == ERRORS diff --git a/src/compat/nanomsg/nn.c b/src/compat/nanomsg/nn.c index a95481bf..ee237c40 100644 --- a/src/compat/nanomsg/nn.c +++ b/src/compat/nanomsg/nn.c @@ -795,3 +795,12 @@ nn_term(void) // in a library -- only e.g. atexit() and similar. nng_closeall(); } + +uint64_t +nn_get_statistic(int x, int y) +{ + (void) x; + (void) y; + + return (0); +}
\ No newline at end of file |