nn_allocmsg(3compat)

Date: Sat, 14 Apr 2018 12:08:12 -0700 Subject: man page updates for tip --- man/tip/index.html | 84 ++- man/tip/nn_allocmsg.3compat.html | 631 ++++++++++++++++++++++ man/tip/nn_bind.3compat.html | 655 +++++++++++++++++++++++ man/tip/nn_close.3compat.html | 605 +++++++++++++++++++++ man/tip/nn_cmsg.3compat.html | 620 ++++++++++++++++++++++ man/tip/nn_connect.3compat.html | 647 +++++++++++++++++++++++ man/tip/nn_device.3compat.html | 608 +++++++++++++++++++++ man/tip/nn_errno.3compat.html | 776 +++++++++++++++++++++++++++ man/tip/nn_freemsg.3compat.html | 588 +++++++++++++++++++++ man/tip/nn_get_statistic.3compat.html | 585 +++++++++++++++++++++ man/tip/nn_getsockopt.3compat.html | 958 ++++++++++++++++++++++++++++++++++ man/tip/nn_reallocmsg.3compat.html | 622 ++++++++++++++++++++++ man/tip/nn_recv.3compat.html | 652 +++++++++++++++++++++++ man/tip/nn_recvmsg.3compat.html | 686 ++++++++++++++++++++++++ man/tip/nn_send.3compat.html | 661 +++++++++++++++++++++++ man/tip/nn_sendmsg.3compat.html | 704 +++++++++++++++++++++++++ man/tip/nn_setsockopt.3compat.html | 913 ++++++++++++++++++++++++++++++++ man/tip/nn_shutdown.3compat.html | 609 +++++++++++++++++++++ man/tip/nn_socket.3compat.html | 749 ++++++++++++++++++++++++++ man/tip/nn_strerror.3compat.html | 586 +++++++++++++++++++++ man/tip/nn_term.3compat.html | 608 +++++++++++++++++++++ man/tip/nng.7.html | 10 +- man/tip/nng_compat.3compat.html | 192 ++++--- man/tip/nng_ctx.5.html | 2 +- man/tip/nng_device.3.html | 3 +- 25 files changed, 13680 insertions(+), 74 deletions(-) create mode 100644 man/tip/nn_allocmsg.3compat.html create mode 100644 man/tip/nn_bind.3compat.html create mode 100644 man/tip/nn_close.3compat.html create mode 100644 man/tip/nn_cmsg.3compat.html create mode 100644 man/tip/nn_connect.3compat.html create mode 100644 man/tip/nn_device.3compat.html create mode 100644 man/tip/nn_errno.3compat.html create mode 100644 man/tip/nn_freemsg.3compat.html create mode 100644 man/tip/nn_get_statistic.3compat.html create mode 100644 man/tip/nn_getsockopt.3compat.html create mode 100644 man/tip/nn_reallocmsg.3compat.html create mode 100644 man/tip/nn_recv.3compat.html create mode 100644 man/tip/nn_recvmsg.3compat.html create mode 100644 man/tip/nn_send.3compat.html create mode 100644 man/tip/nn_sendmsg.3compat.html create mode 100644 man/tip/nn_setsockopt.3compat.html create mode 100644 man/tip/nn_shutdown.3compat.html create mode 100644 man/tip/nn_socket.3compat.html create mode 100644 man/tip/nn_strerror.3compat.html create mode 100644 man/tip/nn_term.3compat.html diff --git a/man/tip/index.html b/man/tip/index.html index afa001b9..b5d8d84a 100644 --- a/man/tip/index.html +++ b/man/tip/index.html @@ -877,7 +877,9 @@ callable by applications.

Section 3compat: Compatible Library Functions

This section documents the nanomsg 1.0 libary compatible functions.

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.

@@ -886,6 +888,86 @@ callable by applications.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/man/tip/nn_allocmsg.3compat.html b/man/tip/nn_allocmsg.3compat.html new file mode 100644 index 00000000..33861666 --- /dev/null +++ b/man/tip/nn_allocmsg.3compat.html @@ -0,0 +1,631 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nn_allocmsg(3compat) + + + + + + + +

SYNOPSIS

#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.

nn_allocmsg(3compat)

allocate message (compatible API)

nn_bind(3compat)

accept connections from remote peers (compatible API)

nn_close(3compat)

close socket (compatible API)

nn_cmsg(3compat)

message control data (compatible API)

nn_connect(3compat)

connect to remote peer (compatible API)

nn_device(3compat)

create forwarding device (compatible API)

nn_errno(3compat)

return most recent error (compatible API)

nn_freemsg(3compat)

free message (compatible API)

nn_get_statistic(3compat)

get statistic (stub)

nn_getsockopt(3compat)

get socket option (compatible API)

nn_reallocmsg(3compat)

reallocate message (compatible API)

nn_recv(3compat)

receive data (compatible API)

nn_recvmsg(3compat)

receive message (compatible API)

nn_send(3compat)

send data (compatible API)

nn_sendmsg(3compat)

send message (compatible API)

nn_setsockopt(3compat)

set socket option (compatible API)

nn_shutdown(3compat)

shut down endpoint (compatible API)

nn_socket(3compat)

create socket (compatible API)

nn_strerror(3compat)

return message for error (compatible API)

nn_term(3compat)

terminate library (compatible API)

nng_compat(3compat)

compatibility with nanomsg 1.0

+ + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant 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() or +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

+ + + + + + + + + + + + + +

+`ENOMEM` +	+ Insufficient memory is available. +
+`EINVAL` +	+ An invalid size or type was specified. +
+`ETERM` +	+ The library is shutting down. +

SYNOPSIS

#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()` to +“unbind” the socket from the address at url.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +

+ + + + + +

+ +	+The bind operation is performed asynchronously, and may not have +completed before this function returns control to the caller. +

+ + + + + +

+ +	+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 modern API to use other schemes.) +

RETURN VALUES

This function returns a positive identifier on success, and -1 on error.

ERRORS

+ + + + + + + + + + + + + + + + + +

+`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. +

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +

RETURN VALUES

This function returns zero on success, and -1 on failure.

ERRORS

+ + + + + + + + + +

+`EBADF` +	+ The socket is not open. +
+`ETERM` +	+ The library is shutting down. +

SYNOPSIS

#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() +or received by nn_recvmsg().

+ + + + + +

+ +	+This structure and supporting macros are provided for API +compatibility with legacy libnanomsg. +Consider using the relevant 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.
+

SYNOPSIS

#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()` to +“unbind” the socket from the address at url.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +

+ + + + + +

+ +	+The connect operation is performed asynchronously, and may not have +completed before this function returns control to the caller. +

+ + + + + +

+ +	+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 modern API to use other schemes.) +

RETURN VALUES

This function returns a positive identifier success, and -1 on error.

ERRORS

+ + + + + + + + + + + + + +

+`ECONNREFUSED` +	+ The connection attempt was refused. +
+`EBADF` +	+ The socket sock is not open. +
+`EINVAL` +	+ An invalid url was supplied. +

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +

The two sockets must be compatible, and must be raw mode +sockets. +More detail about devices and how they can be used is available in the +new style 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

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.
+

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +

+ + + + + +

+ + +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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+`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. +

SYNOPSIS

#include <nanomsg/nn.h>
+
+int nn_freemsg(void *msg);

DESCRIPTION

The nn_freemsg() deallocates a message previously allocated with +nn_allocmsg()` or similar functions.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +

RETURN VALUES

This function always returns 0.

ERRORS

None.

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +

RETURN VALUES

Zero.

ERRORS

None.

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant 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.

+ + + + + +

+ +	+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:

+ + + + + + + + + + + + + + + + + +

+`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.
+

+ + + + + +

+ +

+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.
+

+ + + + + +

+ +	+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.
+

+ + + + + +

+ + +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 +device chains.
+

+ + + + + +

+ +	+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.
+

+ + + + + +

+ +	+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.
+

+ + + + + +

+ +	+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

+ + + + + + + + + + + + + + + + + + + + + + + + + +

+`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. +

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant 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

+ + + + + + + + + + + + + +

+`ENOMEM` +	+ Insufficient memory is available. +
+`EINVAL` +	+ An invalid size was specified. +
+`ETERM` +	+ The library is shutting down. +

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant 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()), 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()) or +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

+ + + + + + + + + + + + + + + + + + + + + +

+`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. +

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant 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:

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() +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 raw mode sockets. +In all other circumstances these fields should be zero. +Details about this structure are covered in +nn_cmsg(3compat).

RETURN VALUES

This function returns the number of bytes received on success, and -1 on error.

ERRORS

+ + + + + + + + + + + + + + + + + + + + + + + + + +

+`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. +

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant 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() or +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.

+ + + + + +

+ +	+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

+ + + + + + + + + + + + + + + + + + + + + +

+`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. +

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +

The hdr points to a structure of type struct nn_msghdr, which has the +following definition:

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()), 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 raw mode sockets. +In all other circumstances these fields should be zero. +Details about this structure are covered in +nn_cmsg(3compat).

+ + + + + +

+ +	+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

+ + + + + + + + + + + + + + + + + + + + + + + + + +

+`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. +

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant 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:

+ + + + + + + + + + + + + + + + + +

+`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.
+

+ + + + + +

+ +

+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.
+

+ + + + + +

+ +	+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.
+

+ + + + + +

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 +device chains.
+

+ + + + + +

+ +	+Not all protocols offer this protection, so care should still be used +in configuring device forwarding. +

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.
+

+ + + + + +

+ +	+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

+ + + + + + + + + + + + + + + + + + + + + + + + + +

+`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. +

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +

RETURN VALUES

This function returns zero on success, and -1 on error.

ERRORS

+ + + + + + + + + +

+`EBADF` +	+ The socket sock is not open. +
+`EINVAL` +	+ An invalid ep was supplied. +

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +

+ + + + + +

+ +	+Mixing the compatibility API and the modern API is not supported +on a given socket. +

+ + + + + +

+ +	+Some protocols, transports, and features are only available in the modern API. +

The address family af can be one of two values:

+ + + + + + + + + +

+`AF_SP` +	+ Normal socket. +
+`AF_SP_RAW` +	+ “Raw mode” socket. +

The protocol indicates the protocol to be used when creating the socket. +The following protocols are defined:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+`NN_PAIR` +	+ Pair protocol. +
+`NN_PUB` +	+ Publisher protocol. +
+`NN_SUB` +	+ Subscriber protocol. +
+`NN_REQ` +	+ Requestor protocol. +
+`NN_REP` +	+ Replier protocol. +
+`NN_PUSH` +	+ Push protocol. +
+`NN_PULL` +	+ Pull protocol. +
+`NN_SURVEYOR` +	+ Surveyor protocol. +
+`NN_RESPONDENT` +	+ Respondent protocol. +
+`NN_BUS` +	+ Bus protocol. +

RETURN VALUES

This function returns a valid socket number on success, and -1 on failure.

ERRORS

+ + + + + + + + + + + + + +

+`ENOMEM` +	+ Insufficient memory is available. +
+`ENOTSUP` +	+ The protocol is not supported. +
+`ETERM` +	+ The library is shutting down. +

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +

RETURN VALUES

This function returns the message corresponding to err.

ERRORS

None.

SYNOPSIS

#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.

+ + + + + +

+ +	+This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +

+ + + + + +

+ + +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.

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.

-- cgit v1.2.3-70-g09d2

`nn_getsockopt()`	get socket option	+`nn_socket()` +	+ create socket +
`nn_setsockopt()`	set socket option	+`nn_getsockopt()` +	+ get socket option +
`nn_bind()`	accept connections from remote peers	+`nn_setsockopt()` +	+ set socket option +
`nn_connect()`	connect to remote peer	+`nn_bind()` +	+ accept connections from remote peers +
`nn_send()`	send data	+`nn_connect()` +	+ connect to remote peer +
`nn_recv()`	receive data	+`nn_send()` +	+ send data +
`nn_shutdown()`	shut down endpoint	+`nn_recv()` +	+ receive data +
`nn_close()`	close socket	+`nn_shutdown()` +	+ shut down endpoint +
`nn_poll()`	poll sockets	+`nn_close()` +	+ close socket +
`nn_device()`	create forwarding device	+`nn_device()` +	+ create forwarding device +
`nn_recvmsg()`	receive message	+`nn_recvmsg()` +	+ receive message +
`nn_sendmsg()`	send message	+`nn_sendmsg()` +	+ send message +
`nn_get_statistic()`	get statistic (stub)	+`nn_cmsg()` +	+ message control data +
`nn_allocmsg()`	allocate message	+`nn_get_statistic()` +	+ get statistic (stub) +
`nn_reallocmsg()`	reallocate message	+`nn_allocmsg()` +	+ allocate message +
`nn_freemsg()`	free message	+`nn_reallocmsg()` +	+ reallocate message +
`nn_errno()`	return most recent error	+`nn_freemsg()` +	+ free message +
`nn_strerror()`	return message for error	+`nn_errno()` +	+ return most recent error +
`nn_term()`	terminate library	+`nn_strerror()` +	+ return message for error +

Section 3compat: Compatible Library Functions

nn_allocmsg(3compat) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nn_bind(3compat) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nn_close(3compat) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nn_cmsg(3compat) Manual Page

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

nn_connect(3compat) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nn_device(3compat) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nn_errno(3compat) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nn_freemsg(3compat) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nn_get_statistic(3compat) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nn_getsockopt(3compat) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nn_reallocmsg(3compat) Manual Page

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

nn_recv(3compat) Manual Page

NAME

SYNOPSIS

DESCRIPTION