diff options
| -rw-r--r-- | docs/man/nng_duration.adoc | 49 | ||||
| -rw-r--r-- | docs/man/nng_options.adoc | 73 | ||||
| -rw-r--r-- | docs/man/nng_socket.adoc | 54 | ||||
| -rw-r--r-- | docs/man/nng_version.adoc | 19 |
4 files changed, 157 insertions, 38 deletions
diff --git a/docs/man/nng_duration.adoc b/docs/man/nng_duration.adoc new file mode 100644 index 00000000..e4417609 --- /dev/null +++ b/docs/man/nng_duration.adoc @@ -0,0 +1,49 @@ += nng_duration(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_duration - relative time in milliseconds + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +typedef int32_t nng_duration; + +#define NNG_DURATION_INFINITE (-1) +#define NNG_DURATION_DEFAULT (-2) +#define NNG_DURATION_ZERO (0) +----------- + +== DESCRIPTION + +An ((`nng_duration`))(((duration))) is a relative time, measured in +milliseconds. +This type is most often used in conjuction with timers and timeouts. + +A couple of special values have been set aside, and carry special meanings. + +[[NNG_DURATION_DEFAULT]]((`NNG_DURATION_DEFAULT`))::: +Indicates a context-specific default value should be used. + +[[NNG_DURATION_INFINITE]]((`NNG_DURATION_INFINITE`))::: +Effectively an infinite duration; used most often to disable timeouts. + +[[NNG_DURATION_ZERO]]((`NNG_DURATION_ZERO`))::: +Zero length duration; used to perform a single polling operation. + +== SEE ALSO +[.text-left] +<<nng_options#,nng_options(5)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_options.adoc b/docs/man/nng_options.adoc index 045618b3..9546e0dc 100644 --- a/docs/man/nng_options.adoc +++ b/docs/man/nng_options.adoc @@ -39,14 +39,24 @@ nng_options - socket, dialer, listener, and pipe options == DESCRIPTION -This page documents the various standard options that can be used -with sockets (see `<<nng_getopt#,nng_getopt(3)>>` -and `<<nng_setopt#,nng_setopt(3)>>`), -dialers (see `<<nng_dialer_getopt#,nng_dialer_getopt(3)>>` -and `<<nng_dialer_setopt#,nng_dialer_setopt(3)>>`), -listeners (see `<<nng_listener_getopt#,nng_listener_getopt(3)>>` -and `<<nng_listener_setopt#,nng_listener_setopt(3)>>`), -and pipes (see `<<nng_pipe_getopt#,nng_pipe_getopt(3)>>`). +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 @@ -65,7 +75,7 @@ description of the option. [[NNG_OPT_LINGER]] ((`NNG_OPT_LINGER`)):: (((lingering))) -(`<<nng_types#nng_duration,nng_duration>>`) +(`<<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 @@ -77,7 +87,7 @@ of undelivered messages. [[NNG_OPT_LOCADDR]] ((`NNG_OPT_LOCADDR`)):: -(`<<nng_types#nng_sockaddr,nng_sockaddr>>`) +(`<<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 @@ -93,14 +103,14 @@ 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(7)>> socket would +(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_types#nng_duration,nng_duration>>`) +(`<<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 @@ -111,7 +121,7 @@ The option is irrelevant for listeners. ((`NNG_OPT_RECONNMAXT`)):: (((`NNG_OPT_RECONNMAXT`))) (((reconnect time, maximum))) -(`<<nng_types#nng_duration,nng_duration>>`) +(`<<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. @@ -141,8 +151,12 @@ has accepted them for delivery. (((receive, polling))) (`int`) This read-only option is used to obtain an integer file descriptor suitable -for use in `poll()`, `select()`, (or on Windows systems `WSApoll()`) and -similar functions. +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* @@ -151,14 +165,14 @@ 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_types#nng_socket,nng_socket>>`) with polling functions, +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(3)>>`. +objects instead. See <<nng_aio_alloc#,`nng_aio_alloc()`>>. [[NNG_OPT_RECVMAXSZ]] ((`NNG_OPT_RECVMAXSZ`)):: @@ -180,14 +194,14 @@ NOTE: Some transports may have further message size restrictions! ((`NNG_OPT_RECVTIMEO`)):: (((receive, timeout))) (((timeout, receive))) -(`<<nng_types#nng_duration,nng_duration>>`) +(`<<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_types#nng_sockaddr,nng_sockaddr>>`) +(`<<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. @@ -203,7 +217,7 @@ 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(7)>> will +generally multicast protocols like <<nng_pub#,nng_pub>> will simply discard messages when they cannot be delivered immediately. [[NNG_OPT_SENDFD]] @@ -213,8 +227,12 @@ simply discard messages when they cannot be delivered immediately. (((send, polling))) (`int`) This read-only option is used to obtain an integer file descriptor suitable -for use in `poll()`, `select()`, (or on Windows systems `WSApoll()`) and -similar functions. +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, @@ -223,20 +241,20 @@ 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_types#nng_socket,nng_socket>>`) with polling functions, +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(3)>>`. +objects instead. See <<nng_aio_alloc#,`nng_aio_alloc`()>>. [[NNG_OPT_SENDTIMEO]] ((`NNG_OPT_SENDTIMEO`)):: (((send, timeout))) (((timeout, send))) -(`<<nng_types#nng_duration,nng_duration>>`) +(`<<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 @@ -256,12 +274,9 @@ The string must fit within 64-bytes, including the terminating (`int`) (((time-to-live))) This is the maximum number of "`hops`" a message may traverse (see -`<<nng_device#,nng_device(3)>>`). +<<nng_device#,`nng_device()`>>). The intention here is to prevent ((forwarding loops)) in device chains. -// ((`NNG_OPT_REMADDR`)):: Endpoint specific, readonly -// ((`NNG_OPT_LOCADDR`)):: Endpoint specific, readonly - [[NNG_OPT_URL]] ((`NNG_OPT_URL`)):: (((URI))) diff --git a/docs/man/nng_socket.adoc b/docs/man/nng_socket.adoc new file mode 100644 index 00000000..31df4a8f --- /dev/null +++ b/docs/man/nng_socket.adoc @@ -0,0 +1,54 @@ += nng_socket(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_socket - socket handle + +== SYNOPSIS + +[source, c] +----------- +#include <nng/nng.h> + +typedef uint32_t nng_socket; +----------- + +== DESCRIPTION + +An ((`nng_socket`))(((socket))) is a handle to an underlying "`socket`" object. +All communication between the application and remote Scalability Protocol +peers is done through sockets. +A given socket can have multiple dialers (<<nng_dialer#,`nng_dialer`>>) +and/or (<<nng_listener#,`nng_listener`>>), and multiple +pipes (<<nng_pipe#,`nng_pipe`>>), and +may be connected to multiple transports at the same time. +However, a given socket will have exactly one "`protocol`" associated with it, +and is responsible for any state machines or other protocol-specific logic. + +NOTE: Although `nng_socket` is an integer data type, these objects are not +ordinary file descriptors, and can only be used with the functions that +explicitly indicate that it safe and appropropate to do so. + +Each `nng_socket` is created by a protocol-specific constructor, such as +<<nng_rep0_open#,`nng_rep0_open()`>>. +When the socket is no longer needed, it can be closed with +<<nng_close#,`nng_close()`>>. + +== SEE ALSO + +[.text-left] +<<libnng#,libnng(3)>>, +<<nng_close#,nng_close(3)>>, +<<nng_dialer#,nng_dialer(5)>>, +<<nng_listener#,nng_listener(5)>>, +<<nng_options#,nng_options(5)>>, +<<nng#,nng(7)>> diff --git a/docs/man/nng_version.adoc b/docs/man/nng_version.adoc index 3f69b0ca..bc578682 100644 --- a/docs/man/nng_version.adoc +++ b/docs/man/nng_version.adoc @@ -24,27 +24,28 @@ const char * nng_version(void); == DESCRIPTION -The `nng_version()` function returns a human readable version -number for the _nng_ library. This is intended for output in -programs, and so forth. +The ((`nng_version()`)) function returns a human readable ((version number)) +for the _nng_ library. +This is intended for output in programs, and so forth. Additionally, compile time version information is available via some predefined macros: -`NNG_MAJOR_VERSION`:: Major version number. -`NNG_MINOR_VERSION`:: Minor version number. -`NNG_PATCH_VERSION`:: Patch version number. +((`NNG_MAJOR_VERSION`)):: Major version number. +((`NNG_MINOR_VERSION`)):: Minor version number. +((`NNG_PATCH_VERSION`)):: Patch version number. The _nng_ library is developed and released using -http:///www.semver.org[Semantic Versioning 2.0], and +http://www.semver.org[Semantic Versioning 2.0], and the version numbers reported refer to both the API and the -library itself. (The ABI -- binary interface -- between the +library itself. +(The ((ABI)) -- ((application binary interface)) -- between the library and the application is controlled in a similar, but different manner depending upon the link options and how the library is built.) == RETURN VALUES -C string (NUL-terminated) containing the library version number. +C string (`NUL`-terminated) containing the library version number. == ERRORS |