From 74a12ffc8b37f2dae4b3002e86f33b8ca52df22d Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 29 Dec 2019 23:21:33 -0800 Subject: man page updates for 1.2 --- man/v1.2/nng_options.5.html | 1074 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1074 insertions(+) create mode 100644 man/v1.2/nng_options.5.html (limited to 'man/v1.2/nng_options.5.html') diff --git a/man/v1.2/nng_options.5.html b/man/v1.2/nng_options.5.html new file mode 100644 index 00000000..97c0b29c --- /dev/null +++ b/man/v1.2/nng_options.5.html @@ -0,0 +1,1074 @@ +--- +version: 1.2 +layout: refman +--- + + + + + + + +nng_options(5) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#include <nng/nng.h>
+
+#define NNG_OPT_SOCKNAME      "socket-name"
+#define NNG_OPT_RAW           "raw"
+#define NNG_OPT_PROTO         "protocol"
+#define NNG_OPT_PROTONAME     "protocol-name"
+#define NNG_OPT_PEER          "peer"
+#define NNG_OPT_PEERNAME      "peer-name"
+#define NNG_OPT_RECVBUF       "recv-buffer"
+#define NNG_OPT_SENDBUF       "send-buffer"
+#define NNG_OPT_RECVFD        "recv-fd"
+#define NNG_OPT_SENDFD        "send-fd"
+#define NNG_OPT_RECVTIMEO     "recv-timeout"
+#define NNG_OPT_SENDTIMEO     "send-timeout"
+#define NNG_OPT_LOCADDR       "local-address"
+#define NNG_OPT_REMADDR       "remote-address"
+#define NNG_OPT_URL           "url"
+#define NNG_OPT_MAXTTL        "ttl-max"
+#define NNG_OPT_RECVMAXSZ     "recv-size-max"
+#define NNG_OPT_RECONNMINT    "reconnect-time-min"
+#define NNG_OPT_RECONNMAXT    "reconnect-time-max"
+
+
+
+
+
+

DESCRIPTION

+
+
+

This page documents the various standard options that can be set or +retrieved on objects in the nng library.

+
+
+

Sockets (nng_socket objects) use the functions +nng_getopt() +and nng_setopt() to set and retrieve option values.

+
+
+

Dialers (nng_dialer objects) use the functions +nng_dialer_getopt() and +nng_dialer_setopt() to set and retrieve option +values.

+
+
+

Listeners (nng_listener objects) use the functions +nng_listener_getopt() +and nng_listener_setopt() to set and +retrieve option values.

+
+
+

Pipes (nng_pipe objects) can only retrieve option values using +the nng_pipe_getopt() function.

+
+
+

Other object types may have additional methods to access these options.

+
+
+

In addition to the options listed here, transports and protocols will generally +have some of their own options, which will be documented with the transport +or protocol.

+
+
+

Generic Options

+
+

In the following list of options, the name of the option is supplied, +along with the data type of the underlying value.

+
+
+

Some options are only meaningful or supported in certain contexts; for +example there is no single meaningful address for a socket, since sockets +can have multiple dialers and endpoints associated with them. +An attempt has been made to include details about such restrictions in the +description of the option.

+
+
+
+
NNG_OPT_LOCADDR
+
+

(nng_sockaddr) +This read-only option may be used on listeners, dialers and connected pipes, and +represents the local address used for communication. +NOTE: Not all transports support this option, and some transports may support it on +listeners but not dialers.

+
+

When used on a TCP dialer, this option is used to configure the source IP +address that will be used when initiating outgoing connections. +The specific port number will be ignored, however, and the system will +choose a random ephemeral port instead.

+
+
+
+
+
+
+
NNG_OPT_RAW
+
+

+ +(bool) +This read-only option indicates whether the socket is in “raw” mode. +If true, the socket is in “raw” mode, and if false the socket is +in “cooked” mode.

+
+

Raw mode sockets generally do not have any protocol-specific semantics applied +to them; instead the application is expected to perform such semantics itself. +(For example, in “cooked” mode a rep socket would +automatically copy message headers from a received message to the corresponding +reply, whereas in “raw” mode this is not done.) +See Raw Mode for more details.

+
+
+
+
+
+
+
NNG_OPT_RECONNMINT
+
+

+(nng_duration) +This is the minimum amount of time (milliseconds) to wait before attempting +to establish a connection after a previous attempt has failed. +This can be set on a socket, but it can also be overridden on an individual +dialer. +The option is irrelevant for listeners.

+
+
+
+
+
+
NNG_OPT_RECONNMAXT
+
+

+ +(nng_duration) +This is the maximum amount of time +(milliseconds) to wait before attempting to establish a connection after +a previous attempt has failed. +If this is non-zero, then the time between successive connection attempts +will start at the value of NNG_OPT_RECONNMINT, +and grow exponentially, until it reaches this value. +If this value is zero, then no exponential +back-off between connection attempts is done, and each attempt will wait +the time specified by NNG_OPT_RECONNMINT. +This can be set on a socket, but it can also be overridden on an individual +dialer. +The option is irrelevant for listeners.

+
+
+
+
+
+
NNG_OPT_RECVBUF
+
+

+ +(int) +This is the depth of the socket’s receive buffer as a number of messages. +Messages received by a transport may be buffered until the application +has accepted them for delivery.

+
+
+
+
+
+
NNG_OPT_RECVFD
+
+

+ + +(int) +This read-only option is used to obtain an integer file descriptor suitable +for use with +poll(), +select(), +(or on Windows systems +WSAPoll()) +and similar functions. +This descriptor will be readable when a message is available for receiving +on the socket. +When no message is ready for receiving, then this file descriptor will not +be readable.

+
+ + + + + +
+ + +Applications should never attempt to read or write to the +returned file descriptor. +
+
+
+ + + + + +
+ + +This option is incompatible with +nng_ctx contexts and should not be used on a socket +where they are in use. +
+
+
+ + + + + +
+ + +While this option may help applications integrate into existing polling +loops, it is more efficient, and often easier, to use the asynchronous I/O +objects instead. +See nng_aio_alloc(). +
+
+
+
+
+
+
+
NNG_OPT_RECVMAXSZ
+
+

+(size_t) +This is the maximum message size that the will be accepted from a remote peer. +If a peer attempts to send a message larger than this, then the message +will be discarded. +If the value of this is zero, then no limit on message sizes is enforced. +This option exists to prevent certain kinds of denial-of-service attacks, +where a malicious agent can claim to want to send an extraordinarily +large message, without sending any data. +This option can be set for the socket, but may be overridden for on a +per-dialer or per-listener basis.

+
+ + + + + +
+ + +Applications on hostile networks should set this to a non-zero +value to prevent denial-of-service attacks. +
+
+
+ + + + + +
+ + +Some transports may have further message size restrictions. +
+
+
+
+
+
+
+
NNG_OPT_RECVTIMEO
+
+

+ +(nng_duration) +This is the socket receive timeout in milliseconds. +When no message is available for receiving at the socket for this period of +time, receive operations will fail with a return value of NNG_ETIMEDOUT.

+
+
+
+
+
+
NNG_OPT_REMADDR
+
+

(nng_sockaddr) +This read-only option may be used on dialers and connected pipes, and +represents the address of a remote peer. +Not all transports support this option.

+
+
+
+
+
+
NNG_OPT_SENDBUF
+
+

+ +(int) +This is the depth of the socket send buffer as a number of messages. +Messages sent by an application may be buffered by the socket until a +transport is ready to accept them for delivery. +This value must be an integer between 0 and 8192, inclusive.

+
+ + + + + +
+ + +Not all protocols support buffering sent messages; +generally multicast protocols like pub will +simply discard messages when they cannot be delivered immediately. +
+
+
+
+
+
+
+
NNG_OPT_SENDFD
+
+

+ + +(int) +This read-only option is used to obtain an integer file descriptor suitable +for use with +poll(), +select(), +(or on Windows systems +WSAPoll()) +and similar functions.

+
+

This descriptor will be readable when the socket is able to accept a +message for sending without blocking. +When the socket is no longer able to accept such messages without blocking, +the descriptor will not be readable.

+
+
+ + + + + +
+ + +Applications should never attempt to read or write to the +returned file descriptor; use should be limited to polling system calls only. +
+
+
+ + + + + +
+ + +This option is incompatible with +nng_ctx contexts and should not be used on a socket +where they are in use. +
+
+
+ + + + + +
+ + +While this option may help applications integrate into existing polling +loops, it is more efficient, and often easier, to use the asynchronous I/O +objects instead. +See nng_aio_alloc(). +
+
+
+
+
+
+
+
NNG_OPT_SENDTIMEO
+
+

+ +(nng_duration) +This is the socket send timeout in milliseconds. +When a message cannot be queued for delivery by the socket for this period of +time (such as if send buffers are full), the operation will fail with a +return value of NNG_ETIMEDOUT.

+
+
+
+
+
+
NNG_OPT_SOCKNAME
+
+

+(string) +This the socket name. +By default this is a string corresponding to the value of the socket. +The string must fit within 64-bytes, including the terminating +NUL byte. +The value is intended for application use, and is not used for anything +in the library itself.

+
+
+
+
+
+
NNG_OPT_MAXTTL
+
+

(int) + +This is the maximum number of “hops” a message may traverse across +a nng_device() forwarders. +The intention here is to prevent forwarding loops in device chains. +When this is supported, it can have a value between 1 and 255, inclusive.

+
+ + + + + +
+ + +Not all protocols support this option. +Those that do generally have a default value of 8. +
+
+
+ + + + + +
+ + +Each node along a forwarding path may have its own value for the +maximum time-to-live, and performs its own checks before forwarding a message. +Therefore it is helpful if all nodes in the topology use the same value for +this option. +
+
+
+
+
+
+
+
NNG_OPT_URL
+
+

+ +(string) +This read-only option is used to obtain the URL with which a listener +or dialer was configured. +Accordingly it can only be used with dialers, listeners, and pipes.

+
+ + + + + +
+ + +Some transports will canonify URLs before returning them to the +application. +
+
+
+
+
+
+
+
NNG_OPT_PROTO
+
+

(int) +This read-only option is used to obtain the 16-bit number for the socket’s protocol.

+
+
+
+
+
+
NNG_OPT_PEER
+
+

(int) +This read-only option is used to obtain the 16-bit number of the +peer protocol for the socket.

+
+
+
+
+
+
NNG_OPT_PROTONAME
+
+

(string) +This read-only option is used to obtain the name of the socket’s protocol.

+
+
+
+
+
+
NNG_OPT_PEERNAME
+
+

(string) +This read-only option is used to obtain the name of the peer protocol for +the socket.

+
+
+
+
+
+
+
+

SEE ALSO

+
+
+

nng_dialer_getopt(3), +nng_dialer_setopt(3), +nng_getopt(3), +nng_listener_getopt(3), +nng_listener_setopt(3), +nng_pipe_getopt(3), +nng_setopt(3), +nng_ipc_options(5), +nng_tcp_options(5), +nng_tls_options(5), +nng(7)

+
+
+
+
+ + -- cgit v1.2.3-70-g09d2