205 lines
6.8 KiB
Text
205 lines
6.8 KiB
Text
= nn_setsockopt(3compat)
|
|
//
|
|
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
|
|
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
|
|
//
|
|
// This document is supplied under the terms of the MIT License, a
|
|
// copy of which should be located in the distribution where this
|
|
// file was obtained (LICENSE.txt). A copy of the license may also be
|
|
// found online at https://opensource.org/licenses/MIT.
|
|
//
|
|
|
|
== NAME
|
|
|
|
nn_setsockopt - set socket option (compatible API)
|
|
|
|
== SYNOPSIS
|
|
|
|
[source,c]
|
|
----
|
|
#include <nanomsg/nn.h>
|
|
|
|
int nn_setsockopt(int sock, int level, int option, const void *val, size_t sz);
|
|
----
|
|
|
|
== DESCRIPTION
|
|
|
|
The `nn_setsockopt()` function sets a socket option on socket _sock_,
|
|
affecting the behavior of the socket.
|
|
The option set is determined by the _level_ and _option_.
|
|
The value of the option is set by _val_, and _sz_, which are pointers to
|
|
the actual value and the size of the value, respectively.
|
|
|
|
NOTE: This function is provided for API
|
|
xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_.
|
|
Consider using the relevant xref:libnng.3.adoc[modern API] instead.
|
|
|
|
The _level_ determines whether the option is a generic socket option,
|
|
or is transport-specific.
|
|
The values possible for level are as follows:
|
|
|
|
[horizontal]
|
|
`NN_SOL_SOCKET`:: Generic socket option
|
|
`NN_IPC`:: Transport specific option for IPC.
|
|
`NN_TCP`:: Transport specific option for TCP.
|
|
`NN_WS`:: Transport specific option for WebSocket.
|
|
|
|
The following generic socket options are possible (all are of type `int` and
|
|
thus size 4, unless otherwise indicated.)
|
|
|
|
`NN_SNDBUF`::
|
|
Send buffer size in bytes.
|
|
|
|
NOTE: In _NNG_ buffers are sized as a count of messages rather than
|
|
bytes, and so an attempt to estimate a conversion based upon a predetermined
|
|
message size of 1kB is made.
|
|
The value supplied is rounded up to the nearest value divisible by 1024, and
|
|
then divided by 1024 to convert to a message count.
|
|
Applications that have unusual message sizes may wish to adjust the value
|
|
used here accordingly.
|
|
|
|
`NN_RCVBUF`::
|
|
Receive buffer size in bytes.
|
|
|
|
NOTE: The same caveats for `NN_SNDBUF` apply here as well.
|
|
|
|
`NN_SNDTIMEO`::
|
|
Send time-out in milliseconds.
|
|
Send operations will fail with `ETIMEDOUT` if no message can be received
|
|
after this many milliseconds have transpired since the operation was started.
|
|
A value of -1 means that no timeout is applied.
|
|
|
|
`NN_RCVTIMEO`::
|
|
Receive time-out in milliseconds.
|
|
Receive operations will fail with `ETIMEDOUT` if no message can be received
|
|
after this many milliseconds have transpired since the operation was started.
|
|
A value of -1 means that no timeout is applied.
|
|
|
|
`NN_RCVMAXSIZE`::
|
|
Maximum receive size in bytes.
|
|
The socket will discard messages larger than this on receive.
|
|
The default, 1MB, is intended to prevent denial-of-service attacks.
|
|
The value -1 removes any limit.
|
|
|
|
`NN_RECONNECT_IVL`::
|
|
Reconnect interval in milliseconds.
|
|
After an outgoing connection is closed or fails, the socket will
|
|
automatically attempt to reconnect after this many milliseconds.
|
|
This is the starting value for the time, and is used in the first
|
|
reconnection attempt after a successful connection is made.
|
|
The default is 100.
|
|
|
|
`NN_RECONNECT_IVL_MAX`::
|
|
Maximum reconnect interval in milliseconds.
|
|
Subsequent reconnection attempts after a failed attempt are made at
|
|
exponentially increasing intervals (back-off), but the interval is
|
|
capped by this value.
|
|
If this value is smaller than `NN_RECONNECT_IVL`, then no exponential
|
|
back-off is performed, and each reconnect interval will be determined
|
|
solely by `NN_RECONNECT_IVL`.
|
|
The default is zero.
|
|
|
|
`NN_LINGER`::
|
|
This option is ignored, and exists only for compatibility.
|
|
|
|
NOTE: This option was unreliable in early releases of _libnanomsg_, and
|
|
is unsupported in _NNG_ and recent _libnanomsg_ releases.
|
|
Applications needing assurance of message delivery should either include an
|
|
explicit notification (automatic with the `NN_REQ` protocol) or allow
|
|
sufficient time for the socket to drain before closing the socket or exiting.
|
|
|
|
`NN_SNDPRIO`::
|
|
This option is not implemented at this time.
|
|
|
|
`NN_RCVPRIO`::
|
|
This option is not implemented at this time.
|
|
|
|
`NN_IPV4ONLY`::
|
|
This option is not implemented at this time.
|
|
|
|
`NN_SOCKET_NAME`::
|
|
This option is a string, and represents the socket name.
|
|
It can be changed to help with identifying different sockets with
|
|
their different application-specific purposes.
|
|
|
|
`NN_MAXTTL`::
|
|
Maximum number of times a message may traverse devices or proxies.
|
|
This value, if positive, provides some protection against forwarding loops in
|
|
xref:nng_device.3.adoc[device] chains.
|
|
|
|
NOTE: Not all protocols offer this protection, so care should still be used
|
|
in configuring device forwarding.
|
|
|
|
The following option is available for `NN_REQ` sockets
|
|
using the `NN_REQ` level:
|
|
|
|
`NN_REQ_RESEND_IVL`::
|
|
Request retry interval in milliseconds.
|
|
If an `NN_REQ` socket does not receive a reply to a request within this
|
|
period of time, the socket will automatically resend the request.
|
|
The default value is 60000 (one minute).
|
|
|
|
The following options are available for `NN_SUB` sockets using the `NN_SUB` level:
|
|
|
|
`NN_SUB_SUBSCRIBE`::
|
|
Subscription topic, for `NN_SUB` sockets.
|
|
This sets a subscription topic.
|
|
When a message from a publisher arrives, it is compared against all
|
|
subscriptions.
|
|
If the first _sz_ bytes of the message are not identical to _val_,
|
|
then the message is silently discarded.
|
|
|
|
TIP: To receive all messages, subscribe to an empty topic (_sz_ equal to zero).
|
|
|
|
`NN_SUB_UNSUBSCRIBE`::
|
|
Removes a subscription topic that was earlier established.
|
|
|
|
The following option is available for `NN_SURVEYOR` sockets
|
|
using the `NN_SURVEYOR` level:
|
|
|
|
`NN_SURVEYOR_DEADLINE`::
|
|
Survey deadline in milliseconds for `NN_SURVEYOR` sockets.
|
|
After sending a survey message, the socket will only accept responses
|
|
from respondents for this long.
|
|
Any responses arriving after this expires are silently discarded.
|
|
|
|
In addition, the following transport specific options are offered:
|
|
|
|
`NN_IPC_SEC_ATTR`::
|
|
This `NN_IPC` option is not supported at this time.
|
|
|
|
`NN_IPC_OUTBUFSZ`::
|
|
This `NN_IPC` option is not supported at this time.
|
|
|
|
`NN_IPC_INBUFSZE`::
|
|
This `NN_IPC` option is not supported at this time.
|
|
|
|
`NN_TCP_NODELAY`::
|
|
This `NN_TCP` option is not supported at this time.
|
|
|
|
`NN_WS_MSG_TYPE`::
|
|
This `NN_WS` option is not supported at this time.
|
|
|
|
== RETURN VALUES
|
|
|
|
This function returns zero on success, and -1 on failure.
|
|
|
|
== ERRORS
|
|
|
|
[horizontal]
|
|
`EBADF`:: The socket _sock_ is not an open socket.
|
|
`ENOMEM`:: Insufficient memory is available.
|
|
`ENOPROTOOPT`:: The level and/or option is invalid.
|
|
`EINVAL`:: The option, or the value passed, is invalid.
|
|
`ETERM`:: The library is shutting down.
|
|
`EACCES`:: The option cannot be changed.
|
|
|
|
== SEE ALSO
|
|
|
|
[.text-left]
|
|
xref:nng_socket.5.adoc[nng_socket(5)],
|
|
xref:nn_close.3compat.adoc[nn_close(3compat)],
|
|
xref:nn_errno.3compat.adoc[nn_errno(3compat)],
|
|
xref:nn_getsockopt.3compat.adoc[nn_getsockopt(3compat)],
|
|
xref:nng_compat.3compat.adoc[nng_compat(3compat)],
|
|
xref:nng.7.adoc[nng(7)]
|