diff options
Diffstat (limited to 'docs/man/nn_getsockopt.3compat.adoc')
| -rw-r--r-- | docs/man/nn_getsockopt.3compat.adoc | 216 |
1 files changed, 216 insertions, 0 deletions
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)>> |