'\" t
.\"     Title: nn_getsockopt
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2021-02-08
.\"    Manual: NNG Reference Manual
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "NN_GETSOCKOPT" "3compat" "2021-02-08" "\ \&" "NNG Reference Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
nn_getsockopt \- get socket option (compatible API)
.SH "SYNOPSIS"
.sp
.if n .RS 4
.nf
.fam C
#include <nanomsg/nn.h>

int nn_getsockopt(int sock, int level, int option, void *val, size_t *szp);
.fam
.fi
.if n .RE
.SH "DESCRIPTION"
.sp
The \f(CRnn_getsockopt()\fP function gets a socket option on socket \fIsock\fP.
The option retrieved is determined by the \fIlevel\fP and \fIoption\fP.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
This function is provided for API
compatibility with legacy \fIlibnanomsg\fP.
Consider using the relevant modern API instead.
.sp .5v
.RE
.sp
The value pointed to by \fIszp\fP must be initialized to the size of the buffer
pointed to by \fIval\fP.
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 \fIszp\fP will be updated with the actual
size of the option.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Tip
.ps -1
.br
.sp
To determine the size to receive an option, first call this function
with \fIval\fP set to \f(CRNULL\fP and the value addressed by \fIszp\fP initialized to zero.
.sp .5v
.RE
.sp
The \fIlevel\fP determines whether the option is a generic socket option,
or is transport\-specific.
The values possible for level are as follows:
.sp
\f(CRNN_SOL_SOCKET\fP
.RS 4
Generic socket option
.RE
.sp
\f(CRNN_IPC\fP
.RS 4
Transport specific option for IPC.
.RE
.sp
\f(CRNN_TCP\fP
.RS 4
Transport specific option for TCP.
.RE
.sp
\f(CRNN_WS\fP
.RS 4
Transport specific option for WebSocket.
.RE
.sp
The following generic socket options are possible (all are of type \f(CRint\fP and
thus size 4, unless otherwise indicated.)
.sp
\f(CRNN_SNDBUF\fP
.RS 4
Send buffer size in bytes.
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
In \fINNG\fP 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.
.sp .5v
.RE
.sp
\f(CRNN_RCVBUF\fP
.RS 4
Receive buffer size in bytes.
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
The same caveats for \f(CRNN_SNDBUF\fP apply here as well.
.sp .5v
.RE
.sp
\f(CRNN_SNDTIMEO\fP
.RS 4
Send time\-out in milliseconds.
Send operations will fail with \f(CRETIMEDOUT\fP 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.
.RE
.sp
\f(CRNN_RCVTIMEO\fP
.RS 4
Receive time\-out in milliseconds.
Receive operations will fail with \f(CRETIMEDOUT\fP 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.
.RE
.sp
\f(CRNN_RCVMAXSIZE\fP
.RS 4
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.
.RE
.sp
\f(CRNN_RECONNECT_IVL\fP
.RS 4
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.
.RE
.sp
\f(CRNN_RECONNECT_IVL_MAX\fP
.RS 4
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 \f(CRNN_RECONNECT_IVL\fP, then no exponential
back\-off is performed, and each reconnect interval will be determined
solely by \f(CRNN_RECONNECT_IVL\fP.
The default is zero.
.RE
.sp
\f(CRNN_LINGER\fP
.RS 4
This option is always zero and exists only for compatibility.
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
This option was unreliable in early releases of \fIlibnanomsg\fP, and
is unsupported in \fINNG\fP and recent \fIlibnanomsg\fP releases.
Applications needing assurance of message delivery should either include an
explicit notification (automatic with the \f(CRNN_REQ\fP protocol) or allow
sufficient time for the socket to drain before closing the socket or exiting.
.sp .5v
.RE
.sp
\f(CRNN_SNDPRIO\fP
.RS 4
This option is not implemented at this time.
.RE
.sp
\f(CRNN_RCVPRIO\fP
.RS 4
This option is not implemented at this time.
.RE
.sp
\f(CRNN_IPV4ONLY\fP
.RS 4
This option is not implemented at this time.
.RE
.sp
\f(CRNN_SOCKET_NAME\fP
.RS 4
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.
.RE
.sp
\f(CRNN_MAXTTL\fP
.RS 4
Maximum number of times a message may traverse devices or proxies.
This value, if positive, provides some protection against forwarding loops in
device chains.
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
Not all protocols offer this protection, so care should still be used
in configuring device forwarding.
.sp .5v
.RE
.sp
\f(CRNN_DOMAIN\fP
.RS 4
This option of type \f(CRint\fP represents either the value \f(CRAF_SP\fP or \f(CRAF_SP_RAW\fP,
corresponding to the value that the socket was created with.
.RE
.sp
\f(CRNN_PROTOCOL\fP
.RS 4
This option option of type \f(CRint\fP contains the numeric protocol number
that the socket is used with.
.RE
.sp
\f(CRNN_RCVFD\fP
.RS 4
This option returns a file descriptor suitable for use in with \f(CRpoll()\fP or
\f(CRselect()\fP (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 \f(CRint\fP on all systems except Windows, where it is of
type \f(CRSOCKET\fP.
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
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.
.sp .5v
.RE
.sp
\f(CRNN_SNDFD\fP
.RS 4
This option returns a file descriptor suitable for use in with \f(CRpoll()\fP or
\f(CRselect()\fP (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 \f(CRint\fP on all systems except Windows, where it is of
type \f(CRSOCKET\fP.
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
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 \fIreadability\fP.
.sp .5v
.RE
.sp
The following option is available for \f(CRNN_REQ\fP sockets
using the \f(CRNN_REQ\fP level:
.sp
\f(CRNN_REQ_RESEND_IVL\fP
.RS 4
Request retry interval in milliseconds.
If an \f(CRNN_REQ\fP 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).
.RE
.sp
The following option is available for \f(CRNN_SURVEYOR\fP sockets
using the \f(CRNN_SURVEYOR\fP level:
.sp
\f(CRNN_SURVEYOR_DEADLINE\fP
.RS 4
Survey deadline in milliseconds for \f(CRNN_SURVEYOR\fP 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.
.RE
.sp
In addition, the following transport specific options are offered:
.sp
\f(CRNN_IPC_SEC_ATTR\fP
.RS 4
This \f(CRNN_IPC\fP option is not supported at this time.
.RE
.sp
\f(CRNN_IPC_OUTBUFSZ\fP
.RS 4
This \f(CRNN_IPC\fP option is not supported at this time.
.RE
.sp
\f(CRNN_IPC_INBUFSZE\fP
.RS 4
This \f(CRNN_IPC\fP option is not supported at this time.
.RE
.sp
\f(CRNN_TCP_NODELAY\fP
.RS 4
This \f(CRNN_TCP\fP option is not supported at this time.
.RE
.sp
\f(CRNN_WS_MSG_TYPE\fP
.RS 4
This \f(CRNN_WS\fP option is not supported, as \fINNG\fP only supports binary messages
in this implementation.
.RE
.SH "RETURN VALUES"
.sp
This function returns zero on success, and \-1 on failure.
.SH "ERRORS"
.sp
\f(CREBADF\fP
.RS 4
The socket \fIsock\fP is not an open socket.
.RE
.sp
\f(CRENOMEM\fP
.RS 4
Insufficient memory is available.
.RE
.sp
\f(CRENOPROTOOPT\fP
.RS 4
The level and/or option is invalid.
.RE
.sp
\f(CREINVAL\fP
.RS 4
The option, or the value passed, is invalid.
.RE
.sp
\f(CRETERM\fP
.RS 4
The library is shutting down.
.RE
.sp
\f(CREACCES\fP
.RS 4
The option cannot be changed.
.RE
.SH "SEE ALSO"
.sp
nng_socket(5),
nn_close(3compat),
nn_errno(3compat),
nn_getsockopt(3compat),
nng_compat(3compat),
nng(7)