1= nn_getsockopt(3compat) 2// 3// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> 4// Copyright 2018 Capitar IT Group BV <info@capitar.com> 5// 6// This document is supplied under the terms of the MIT License, a 7// copy of which should be located in the distribution where this 8// file was obtained (LICENSE.txt). A copy of the license may also be 9// found online at https://opensource.org/licenses/MIT. 10// 11 12== NAME 13 14nn_getsockopt - get socket option (compatible API) 15 16== SYNOPSIS 17 18[source,c] 19---- 20#include <nanomsg/nn.h> 21 22int nn_getsockopt(int sock, int level, int option, void *val, size_t *szp); 23---- 24 25== DESCRIPTION 26 27The `nn_getsockopt()` function gets a socket option on socket _sock_. 28The option retrieved is determined by the _level_ and _option_. 29 30NOTE: This function is provided for API 31xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. 32Consider using the relevant xref:libnng.3.adoc[modern API] instead. 33 34The value pointed to by _szp_ must be initialized to the size of the buffer 35pointed to by _val_. 36No more than this many bytes of the option will be copied into the destination 37buffer on success. 38On success, the value pointed to by _szp_ will be updated with the actual 39size of the option. 40 41TIP: To determine the size to receive an option, first call this function 42with _val_ set to `NULL` and the value addressed by _szp_ initialized to zero. 43 44The _level_ determines whether the option is a generic socket option, 45or is transport-specific. 46The values possible for level are as follows: 47 48[horizontal] 49`NN_SOL_SOCKET`:: Generic socket option 50`NN_IPC`:: Transport specific option for IPC. 51`NN_TCP`:: Transport specific option for TCP. 52`NN_WS`:: Transport specific option for WebSocket. 53 54The following generic socket options are possible (all are of type `int` and 55thus size 4, unless otherwise indicated.) 56 57`NN_SNDBUF`:: 58Send buffer size in bytes. 59 60NOTE: In _NNG_ buffers are sized as a count of messages rather than 61bytes; accordingly this value is the queue depth multiplied by 1024 62(representing an estimate that the average message size is 1kB). 63Applications that have unusual message sizes may wish to adjust the value 64used here accordingly. 65 66`NN_RCVBUF`:: 67Receive buffer size in bytes. 68 69NOTE: The same caveats for `NN_SNDBUF` apply here as well. 70 71`NN_SNDTIMEO`:: 72Send time-out in milliseconds. 73Send operations will fail with `ETIMEDOUT` if no message can be received 74after this many milliseconds have transpired since the operation was started. 75A value of -1 means that no timeout is applied. 76 77`NN_RCVTIMEO`:: 78Receive time-out in milliseconds. 79Receive operations will fail with `ETIMEDOUT` if no message can be received 80after this many milliseconds have transpired since the operation was started. 81A value of -1 means that no timeout is applied. 82 83`NN_RCVMAXSIZE`:: 84Maximum receive size in bytes. 85The socket will discard messages larger than this on receive. 86The default, 1MB, is intended to prevent denial-of-service attacks. 87The value -1 removes any limit. 88 89`NN_RECONNECT_IVL`:: 90Reconnect interval in milliseconds. 91After an outgoing connection is closed or fails, the socket will 92automatically attempt to reconnect after this many milliseconds. 93This is the starting value for the time, and is used in the first 94reconnection attempt after a successful connection is made. 95The default is 100. 96 97`NN_RECONNECT_IVL_MAX`:: 98Maximum reconnect interval in milliseconds. 99Subsequent reconnection attempts after a failed attempt are made at 100exponentially increasing intervals (back-off), but the interval is 101capped by this value. 102If this value is smaller than `NN_RECONNECT_IVL`, then no exponential 103back-off is performed, and each reconnect interval will be determined 104solely by `NN_RECONNECT_IVL`. 105The default is zero. 106 107`NN_LINGER`:: 108This option is always zero and exists only for compatibility. 109 110NOTE: This option was unreliable in early releases of _libnanomsg_, and 111is unsupported in _NNG_ and recent _libnanomsg_ releases. 112Applications needing assurance of message delivery should either include an 113explicit notification (automatic with the `NN_REQ` protocol) or allow 114sufficient time for the socket to drain before closing the socket or exiting. 115 116 117`NN_SNDPRIO`:: 118This option is not implemented at this time. 119 120`NN_RCVPRIO`:: 121This option is not implemented at this time. 122 123`NN_IPV4ONLY`:: 124This option is not implemented at this time. 125 126`NN_SOCKET_NAME`:: 127This option is a string, and represents the socket name. 128It can be changed to help with identifying different sockets with 129their different application-specific purposes. 130 131`NN_MAXTTL`:: 132Maximum number of times a message may traverse devices or proxies. 133This value, if positive, provides some protection against forwarding loops in 134xref:nng_device.3.adoc[device] chains. 135 136NOTE: Not all protocols offer this protection, so care should still be used 137in configuring device forwarding. 138 139`NN_DOMAIN`:: 140This option of type `int` represents either the value `AF_SP` or `AF_SP_RAW`, 141corresponding to the value that the socket was created with. 142 143`NN_PROTOCOL`:: 144This option option of type `int` contains the numeric protocol number 145that the socket is used with. 146 147`NN_RCVFD`:: 148This option returns a file descriptor suitable for use in with `poll()` or 149`select()` (or other system-specific polling functions). 150This descriptor will be readable when a message is available for receiving 151at the socket. 152This option is of type `int` on all systems except Windows, where it is of 153type `SOCKET`. 154 155NOTE: The file descriptor should not be read or written by the application, 156and is not the same as any underlying descriptor used for network sockets. 157 158`NN_SNDFD`:: 159This option returns a file descriptor suitable for use in with `poll()` or 160`select()` (or other system-specific polling functions). 161This descriptor will be readable when the socket is able to accept a message 162for sending. 163This option is of type `int` on all systems except Windows, where it is of 164type `SOCKET`. 165 166NOTE: The file descriptor should not be read or written by the application, 167and is not the same as any underlying descriptor used for network sockets. 168Furthermore, the file descriptor should only be polled for _readability_. 169 170The following option is available for `NN_REQ` sockets 171using the `NN_REQ` level: 172 173`NN_REQ_RESEND_IVL`:: 174Request retry interval in milliseconds. 175If an `NN_REQ` socket does not receive a reply to a request within this 176period of time, the socket will automatically resend the request. 177The default value is 60000 (one minute). 178 179The following option is available for `NN_SURVEYOR` sockets 180using the `NN_SURVEYOR` level: 181 182`NN_SURVEYOR_DEADLINE`:: 183Survey deadline in milliseconds for `NN_SURVEYOR` sockets. 184After sending a survey message, the socket will only accept responses 185from respondents for this long. 186Any responses arriving after this expires are silently discarded. 187 188In addition, the following transport specific options are offered: 189 190`NN_IPC_SEC_ATTR`:: 191This `NN_IPC` option is not supported at this time. 192 193`NN_IPC_OUTBUFSZ`:: 194This `NN_IPC` option is not supported at this time. 195 196`NN_IPC_INBUFSZE`:: 197This `NN_IPC` option is not supported at this time. 198 199`NN_TCP_NODELAY`:: 200This `NN_TCP` option is not supported at this time. 201 202`NN_WS_MSG_TYPE`:: 203This `NN_WS` option is not supported, as _NNG_ only supports binary messages 204in this implementation. 205 206== RETURN VALUES 207 208This function returns zero on success, and -1 on failure. 209 210== ERRORS 211 212[horizontal] 213`EBADF`:: The socket _sock_ is not an open socket. 214`ENOMEM`:: Insufficient memory is available. 215`ENOPROTOOPT`:: The level and/or option is invalid. 216`EINVAL`:: The option, or the value passed, is invalid. 217`ETERM`:: The library is shutting down. 218`EACCES`:: The option cannot be changed. 219 220== SEE ALSO 221 222[.text-left] 223xref:nng_socket.5.adoc[nng_socket(5)], 224xref:nn_close.3compat.adoc[nn_close(3compat)], 225xref:nn_errno.3compat.adoc[nn_errno(3compat)], 226xref:nn_getsockopt.3compat.adoc[nn_getsockopt(3compat)], 227xref:nng_compat.3compat.adoc[nng_compat(3compat)], 228xref:nng.7.adoc[nng(7)] 229