From 98f23e10cc1d65da6a7f6c7e4f5665d7afc27a86 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Thu, 15 Mar 2018 08:40:17 -0700
Subject: fixes #286 nng_pair0_open (and all others) need man page fixes #279
 consider restructuring man sections

This represents a rather significant rework, and major editing
effort, for the entire set of manual pages.

All of the pages now have a section number in their filename;
this assists in some other tooling, particularly ebook generation
as every link needs to be programmatically modified when combined
into an ebook.

Section 5 is introduced, and populated with pages for the main
types, and all options are now documented.

Numerous errors have been corrected, including rewriting certain
portions such as the header section of the surveyor protocol.

Much work has been done to facilitate index generation, although
certainly more work remains here.

Every internal link within these pages now resolves; there are no
more dead links.  (This is required to generate Kindle format books.)
---
 docs/man/nng_options.adoc | 300 ----------------------------------------------
 1 file changed, 300 deletions(-)
 delete mode 100644 docs/man/nng_options.adoc

(limited to 'docs/man/nng_options.adoc')

diff --git a/docs/man/nng_options.adoc b/docs/man/nng_options.adoc
deleted file mode 100644
index 9546e0dc..00000000
--- a/docs/man/nng_options.adoc
+++ /dev/null
@@ -1,300 +0,0 @@
-= nng_options(5)
-//
-// 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
-
-nng_options - socket, dialer, listener, and pipe options
-
-== SYNOPSIS
-
-[source, c]
------------
-#include <nng/nng.h>
-
-#define NNG_OPT_SOCKNAME   "socket-name"
-#define NNG_OPT_RAW        "raw"
-#define NNG_OPT_LINGER     "linger"
-#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#,`nng_socket`>>) use the functions
-<<nng_getopt#,`nng_getopt()`>>
-and <<nng_setopt#,`nng_setopt()`>> to set and retrieve option values.
-
-Dialers (<<nng_dialer#,`nng_dialer`>>) use the functions
-<<nng_dialer_getopt#,`nng_dialer_getopt()`>> and
-<<nng_dialer_setopt#,`nng_dialer_setopt()`>> to set and retrieve option values.
-
-Listeners (<<nng_listener#,`nng_listener`>>) use the functions
-<<nng_listener_getopt#,`nng_listener_getopt()`>>
-and <<nng_listener_setopt#,`nng_listener_setopt()`>> to set and retrieve option
-values.
-
-Pipes (<<nng_pipe#,`nng_pipe`>>) can only retrieve option values using
-the <<nng_pipe_getopt#,`nng_pipe_getopt()`>> function.
-
-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.
-
-=== 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_LINGER]]
-((`NNG_OPT_LINGER`))::
-(((lingering)))
-(`<<nng_duration#,nng_duration>>`)
-This is the linger time of the socket in milliseconds.
-When this value is non-zero, then the system will
-attempt to defer closing until it has undelivered data, or until the specified
-timeout has expired.
-
-NOTE: Not all transports support lingering, and
-so closing a socket or exiting the application can still result in the loss
-of undelivered messages.
-
-[[NNG_OPT_LOCADDR]]
-((`NNG_OPT_LOCADDR`))::
-(`<<nng_sockaddr#,nng_sockaddr>>`)
-This read-only option may be used on listeners, dialers and connected pipes, and
-represents the local address used for communication.
-Not all transports support this option, and some transports may support it
-listeners but not dialers.
-
-[[NNG_OPT_RAW]]
-((`NNG_OPT_RAW`))::
-(((raw mode)))
-(((cooked mode)))
-(`bool`)
-This option determines 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 an <<nng_rep#,nng_rep>> socket would
-automatically copy message headers from a received message to the corresponding
-reply, whereas in "`raw`" mode this is not done.)
-
-[[NNG_OPT_RECONNMINT]]
-((`NNG_OPT_RECONNMINT`))::
-(((reconnect time, minimum)))
-(`<<nng_duration#,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_OPT_RECONNMAXT`))::
-(((`NNG_OPT_RECONNMAXT`)))
-(((reconnect time, maximum)))
-(`<<nng_duration#,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,NNG_OPT_RECONNMINT>>`,
-and grow exponentially, until it reaches this value.
-If this value is zero, then no exponential
-backoff between connection attempts is done, and each attempt will wait
-the time specified by `<<NNG_OPT_RECONNMINT,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]]
-((`NNG_OPT_RECVBUF`))::
-(((buffer, receive)))
-(((receive, buffer)))
-(`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]]
-((`NNG_OPT_RECVFD`))::
-(((poll)))
-(((select)))
-(((receive, polling)))
-(`int`)
-This read-only option is used to obtain an integer file descriptor suitable
-for use with
-http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html[`poll()`],
-http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html[`select()`],
-(or on Windows systems
-https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx[`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.
-
-IMPORTANT: Appplications should never attempt to read or write to the
-returned file descriptor.
-Furthermore, applications should not attempt to use the actual socket (of
-type <<nng_socket#,`nng_socket`>>) with polling functions,
-since it is merely an internal
-identifier and will not necessarily referency any operting system object or
-handle.
-
-TIP: 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_aio_alloc()`>>.
-
-[[NNG_OPT_RECVMAXSZ]]
-((`NNG_OPT_RECVMAXSZ`))::
-(((receive, maximum size)))
-(`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.
-
-NOTE: Some transports may have further message size restrictions!
-
-[[NNG_OPT_RECVTIMEO]]
-((`NNG_OPT_RECVTIMEO`))::
-(((receive, timeout)))
-(((timeout, receive)))
-(`<<nng_duration#,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_OPT_REMADDR`))::
-(`<<nng_sockaddr#,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]]
-((`NNG_OPT_SENDBUF`))::
-(((send, buffer)))
-(((buffer, send)))
-(`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.
-
-NOTE: Not all protocols support buffering sent messages;
-generally multicast protocols like <<nng_pub#,nng_pub>> will
-simply discard messages when they cannot be delivered immediately.
-
-[[NNG_OPT_SENDFD]]
-((`NNG_OPT_SENDFD`))::
-(((poll)))
-(((select)))
-(((send, polling)))
-(`int`)
-This read-only option is used to obtain an integer file descriptor suitable
-for use with
-http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html[`poll()`],
-http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html[`select()`],
-(or on Windows systems
-https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx[`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.
-
-IMPORTANT: Appplications should never attempt to read or write to the
-returned file descriptor.
-Furthermore, applications should not attempt to use the actual socket (of
-type <<nng_socket#,`nng_socket`>>) with polling functions,
-since it is merely an internal
-identifier and will not necessarily referency any operting system object or
-handle.
-
-TIP: 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_aio_alloc`()>>.
-
-[[NNG_OPT_SENDTIMEO]]
-((`NNG_OPT_SENDTIMEO`))::
-(((send, timeout)))
-(((timeout, send)))
-(`<<nng_duration#,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]]
-((`NNG_OPT_SOCKNAME`))::
-(((name, socket)))
-(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, but it can be changed for other application uses.
-
-[[NNG_OPT_MAXTTL]]
-((`NNG_OPT_MAXTTL`))::
-(`int`)
-(((time-to-live)))
-This is the maximum number of "`hops`" a message may traverse (see
-<<nng_device#,`nng_device()`>>).
-The intention here is to prevent ((forwarding loops)) in device chains.
-
-[[NNG_OPT_URL]]
-((`NNG_OPT_URL`))::
-(((URI)))
-(((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.
-
-NOTE: Some transports will canonify URLs before returning them to the
-application.
-
-== SEE ALSO
-[.text-left]
-<<nng_dialer_getopt#,nng_dialer_getopt(3)>>,
-<<nng_dialer_setopt#,nng_dialer_setopt(3)>>,
-<<nng_getopt#,nng_getopt(3)>>,
-<<nng_listener_getopt#,nng_listener_getopt(3)>>,
-<<nng_listener_setopt#,nng_listener_setopt(3)>>,
-<<nng_setopt#,nng_setopt(3)>>,
-<<nng#,nng(7)>>
-- 
cgit v1.2.3-70-g09d2

