nn_getsockopt.3compat.adoc

nn_getsockopt(3compat)

NAME

nn_getsockopt - get socket option (compatible API)

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.

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

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:

NN_SOL_SOCKET	Generic socket option
NN_IPC	Transport specific option for IPC.
NN_TCP	Transport specific option for TCP.
NN_WS	Transport specific option for WebSocket.

The following generic socket options are possible (all are of type int and thus size 4, unless otherwise indicated.)

NN_SNDBUF

Send buffer size in bytes.

Note	In NNG buffers are sized as a count of messages rather than bytes; accordingly this value is the queue depth multiplied by 1024 (representing an estimate that the average message size is 1kB). Applications that have unusual message sizes may wish to adjust the value used here accordingly.

NN_RCVBUF

Receive buffer size in bytes.

Note	The same caveats for NN_SNDBUF apply here as well.

NN_SNDTIMEO

Send time-out in milliseconds. Send operations will fail with ETIMEDOUT if no message can be received after this many milliseconds have transpired since the operation was started. A value of -1 means that no timeout is applied.

NN_RCVTIMEO

Receive time-out in milliseconds. Receive operations will fail with ETIMEDOUT if no message can be received after this many milliseconds have transpired since the operation was started. A value of -1 means that no timeout is applied.

NN_RCVMAXSIZE

Maximum receive size in bytes. The socket will discard messages larger than this on receive. The default, 1MB, is intended to prevent denial-of-service attacks. The value -1 removes any limit.

NN_RECONNECT_IVL

Reconnect interval in milliseconds. After an outgoing connection is closed or fails, the socket will automatically attempt to reconnect after this many milliseconds. This is the starting value for the time, and is used in the first reconnection attempt after a successful connection is made. The default is 100.

NN_RECONNECT_IVL_MAX

Maximum reconnect interval in milliseconds. Subsequent reconnection attempts after a failed attempt are made at exponentially increasing intervals (back-off), but the interval is capped by this value. If this value is smaller than NN_RECONNECT_IVL, then no exponential back-off is performed, and each reconnect interval will be determined solely by NN_RECONNECT_IVL. The default is zero.

NN_LINGER

This option is always zero and exists only for compatibility.

Note

This option was unreliable in early releases of libnanomsg, and is unsupported in NNG and recent libnanomsg releases. Applications needing assurance of message delivery should either include an explicit notification (automatic with the NN_REQ protocol) or allow sufficient time for the socket to drain before closing the socket or exiting.

NN_SNDPRIO

This option is not implemented at this time.

NN_RCVPRIO

This option is not implemented at this time.

NN_IPV4ONLY

This option is not implemented at this time.

NN_SOCKET_NAME

This option is a string, and represents the socket name. It can be changed to help with identifying different sockets with their different application-specific purposes.

NN_MAXTTL

Maximum number of times a message may traverse devices or proxies. This value, if positive, provides some protection against forwarding loops in device chains.

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

NN_DOMAIN

This option of type int represents either the value AF_SP or AF_SP_RAW, corresponding to the value that the socket was created with.

NN_PROTOCOL

This option option of type int contains the numeric protocol number that the socket is used with.

NN_RCVFD

This option returns a file descriptor suitable for use in with poll() or select() (or other system-specific polling functions). This descriptor will be readable when a message is available for receiving at the socket. This option is of type int on all systems except Windows, where it is of type SOCKET.

Note	The file descriptor should not be read or written by the application, and is not the same as any underlying descriptor used for network sockets.

NN_SNDFD

This option returns a file descriptor suitable for use in with poll() or select() (or other system-specific polling functions). This descriptor will be readable when the socket is able to accept a message for sending. This option is of type int on all systems except Windows, where it is of type SOCKET.

Note	The file descriptor should not be read or written by the application, and is not the same as any underlying descriptor used for network sockets. Furthermore, the file descriptor should only be polled for readability.

The following option is available for NN_REQ sockets using the NN_REQ level:

NN_REQ_RESEND_IVL

Request retry interval in milliseconds. If an NN_REQ socket does not receive a reply to a request within this period of time, the socket will automatically resend the request. The default value is 60000 (one minute).

The following option is available for NN_SURVEYOR sockets using the NN_SURVEYOR level:

NN_SURVEYOR_DEADLINE

Survey deadline in milliseconds for NN_SURVEYOR sockets. After sending a survey message, the socket will only accept responses from respondents for this long. Any responses arriving after this expires are silently discarded.

In addition, the following transport specific options are offered:

NN_IPC_SEC_ATTR

This NN_IPC option is not supported at this time.

NN_IPC_OUTBUFSZ

This NN_IPC option is not supported at this time.

NN_IPC_INBUFSZE

This NN_IPC option is not supported at this time.

NN_TCP_NODELAY

This NN_TCP option is not supported at this time.

NN_WS_MSG_TYPE

This NN_WS option is not supported, as NNG only supports binary messages in this implementation.

RETURN VALUES

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

ERRORS

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), nn_close(3compat), nn_errno(3compat), nn_getsockopt(3compat), nng_compat(3compat), nng(7)