From 8da1ec98c6d30b809ff09392ae2989a4de9ed71c Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 18 Mar 2018 14:58:21 -0700 Subject: [PATCH] fixes #293 nng_listener_getopt doc needs updating Actually I updated all the option related documents, and fixed minor markup issues on several others. --- docs/man/nng_close.3.adoc | 4 +- docs/man/nng_dialer_getopt.3.adoc | 68 +++++++++++++---------- docs/man/nng_dialer_setopt.3.adoc | 83 ++++++++++++++++------------ docs/man/nng_getopt.3.adoc | 33 +++++------ docs/man/nng_listener_getopt.3.adoc | 74 +++++++++++++++---------- docs/man/nng_listener_setopt.3.adoc | 86 +++++++++++++++++------------ docs/man/nng_pipe_getopt.3.adoc | 52 +++++++++-------- docs/man/nng_setopt.3.adoc | 20 ++++--- docs/man/nng_url_free.3.adoc | 4 +- docs/man/nng_url_parse.3.adoc | 4 +- 10 files changed, 248 insertions(+), 180 deletions(-) diff --git a/docs/man/nng_close.3.adoc b/docs/man/nng_close.3.adoc index 64bbf712f..3f1c68f3a 100644 --- a/docs/man/nng_close.3.adoc +++ b/docs/man/nng_close.3.adoc @@ -16,11 +16,11 @@ nng_close - close socket == SYNOPSIS [source, c] ------------ +---- #include int nng_close(nng_socket s); ------------ +---- == DESCRIPTION diff --git a/docs/man/nng_dialer_getopt.3.adoc b/docs/man/nng_dialer_getopt.3.adoc index 8dad06d1d..61aaa5760 100644 --- a/docs/man/nng_dialer_getopt.3.adoc +++ b/docs/man/nng_dialer_getopt.3.adoc @@ -21,6 +21,8 @@ nng_dialer_getopt - get dialer option int nng_dialer_getopt(nng_dialer d, const char *opt, void *val, size_t *valszp); +int nng_dialer_getopt_bool(nng_dialer d, const char *opt, bool *bvalp); + int nng_dialer_getopt_int(nng_dialer d, const char *opt, int *ivalp); int nng_dialer_getopt_ms(nng_dialer d, const char *opt, nng_duration *durp); @@ -34,22 +36,31 @@ int nng_dialer_getopt_uint64(nng_dialer d, const char *opt, uint64_t *u64p); == DESCRIPTION +(((options, dialer))) The `nng_dialer_getopt()` functions are used to retrieve option values for -the dialer _d_. +the <> _d_. The actual options that may be retrieved in this way vary, and many are documented in <>. -Additionally some transport-specific options are documented with the -transports themselves. + +Additionally some transport-specific options and protocol-specific options +are documented with the transports and protocols themselves. + +=== Forms In all of these forms, the option _opt_ is retrieved from the dialer _d_. +The forms vary based on the type of the option they take. + +TIP: Generally, it will be easier to use one of the typed versions of this +function. + +NOTE: No validation that the option is actually of the associated type is +performed, so the caller must take care to use the *correct* typed form. The details of the type, size, and semantics of the option will depend on the actual option, and will be documented with the option itself. -=== Untyped Form - -The first form of this function, `nng_dialer_getopt()`, can be used to -retrieve the value of any option. +==== `nng_dialer_getopt()` +This function is untyped and can be used to retrieve the value of any option. The caller must store a pointer to a buffer to receive the value in _val_, and the size of the buffer shall be stored at the location referenced by _valszp_. @@ -66,41 +77,39 @@ It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. This can be used to determine the size of the buffer needed to receive the object. -=== Typed Forms - -Generally, it will be easier to use one of the typed forms instead. -Note however that no validation that the option is actually of the associated -type is performed, so the caller must take care to use the *correct* typed -form. +==== `nng_dialer_getopt_bool()` +This function is for options which take a boolean (`bool`). +The value will be stored at _ivalp_. -The second form, `nng_dialer_getopt_int()`, -is for options which take an integer (or boolean). +==== `nng_dialer_getopt_int()` +This function is for options which take an integer (`int`). The value will be stored at _ivalp_. -For booleans the value will be eiher 0 (false) or 1 (true). -The third form, `nng_dialer_getopt_ms()`, is used to retrieve time durations +==== `nng_dialer_getopt_ms()` +This function is used to retrieve time <> (such as timeouts), stored in _durp_ as a number of milliseconds. -(The special value `NNG_DUR_INFINITE` means an infinite amount of time, and -the special value `NNG_DUR_DEFAULT` means a context-specific default.) +(The special value ((`NNG_DUR_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DUR_DEFAULT`)) means a context-specific default.) -The fourth form, `nng_dialer_getopt_ptr()`, is used to retrieve a -pointer _ptr_ to structured data. +==== `nng_dialer_getopt_ptr()` +This function is used to retrieve a pointer, _ptr_, to structured data. The data referenced by _ptr_ is generally managed using other functions. Note that this form is somewhat special in that the object is generally not copied, but instead the *pointer* to the object is copied. -The fifth form, `nng_dialer_getopt_size()`, is used to retrieve a size -into the pointer _zp_, typically for buffer sizes, message maximum sizes, and -similar options. +==== `nng_dialer_getopt_size()` +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. -The sixth form, `nng_dialer_getopt_uint64()`, is used to retrieve a -64-bit unsigned value into the value referenced by _u64p_. -This is typically used for options -related to identifiers, network numbers, and similar. +==== `nng_dialer_getopt_uint64()` +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. == RETURN VALUES -This function returns 0 on success, and non-zero otherwise. +These functions returns 0 on success, and non-zero otherwise. == ERRORS @@ -114,5 +123,6 @@ This function returns 0 on success, and non-zero otherwise. <> <>, <>, +<>, <>, <> diff --git a/docs/man/nng_dialer_setopt.3.adoc b/docs/man/nng_dialer_setopt.3.adoc index 311a61235..1bec71b2a 100644 --- a/docs/man/nng_dialer_setopt.3.adoc +++ b/docs/man/nng_dialer_setopt.3.adoc @@ -22,6 +22,8 @@ nng_dialer_setopt - set dialer option int nng_dialer_setopt(nng_dialer d, const char *opt, const void *val, size_t valsz); +int nng_dialer_setopt_bool(nng_dialer d, const char *opt, bool bval); + int nng_dialer_setopt_int(nng_dialer d, const char *opt, int ival); int nng_dialer_setopt_ms(nng_dialer d, const char *opt, nng_duration dur); @@ -37,64 +39,76 @@ int nng_dialer_setopt_uint64(nng_dialer d, const char *opt, uint64_t u64); == DESCRIPTION +(((options, dialer))) The `nng_dialer_setopt()` functions are used to configure options for -the dialer _d_. +the <> _d_. The actual options that may be configured in this way vary, and many are documented in <>. + Additionally some transport-specific options are documented with the transports themselves. +NOTE: Once a dialer has started, it is generally not possible to change +it's configuration. + +=== Forms + In all of these forms, the option _opt_ is configured on the dialer _d_. The details of the type, size, and semantics of the option will depend on the actual option, and will be documented with the option itself. -The first form of this function, `nng_dialer_setopt()`, can be used to -configure any arbitrary data. -The _val_ pointer addresses the data to copy, and _valsz_ is the -size of the objected located at _val_. - -Generally, it will be easier to use one of the typed forms instead. +TIP: Generally, it will be easier to use one of the typed forms instead. -The second form, `nng_dialer_setopt_int()`, -is for options which take an integer (or boolean). The _ival_ -is passed to the option. For booleans pass either 0 (false) or 1 (true). +NOTE: No validation that the option is actually of the associated +type is performed, so the caller must take care to use the *correct* typed form. -The third form, `nng_dialer_setopt_ms()`, is used to configure time durations -(such as timeouts). -The duration _dur_ is an integer number of milliseconds. (The special value -`NNG_DUR_INFINITE` means an infinite amount of time.) +==== `nng_dialer_setopt()` +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. -The fourth form, `nng_dialer_setopt_ptr()`, is used to pass a -pointer _ptr_ to structured data. The data referenced by _ptr_ is -generally managed by other functions. -For example, TLS configuration objects -(<>) can be passed this way. +==== `nng_dialer_setopt_bool()` +This function is for options which take a boolean (`bool`). +The _bval_ is passed to the option. + +==== `nng_dialer_setopt_int()` +This function is for options which take an integer (`int`). +The _ival_ is passed to the option. + +==== `nng_dialer_setopt_ms()` +This function is used to configure time durations (such as timeouts) using +type <>. +The duration _dur_ is an integer number of milliseconds. + +==== `nng_dialer_setopt_ptr()` +This function is used to pass a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed by other functions. +For example, TLS configuration objects created with +(<>) +can be passed this way. Note that this form is somewhat special in that the object is generally not copied, but instead the *pointer* to the object is copied. -The fifth form, `nng_dialer_setopt_size()`, is used to pass a size -specified by _z_, typically for buffer sizes, message maximum sizes, and -similar options. +==== `nng_dialer_setopt_size()` +This function is used to configure a size, _z_, typically for buffer sizes, +message maximum sizes, and similar options. -The sixth form, `nng_dialer_setopt_string()`, is used to pass a string -_str_. +==== `nng_dialer_setopt_string()` +This function is used to pass configure a string, _str_. Strings passed this way must be legal UTF-8 or ASCII strings, terminated with a `NUL` (`\0`) byte. -(Other constraints may apply as well, see the -documentation for _opt_ for details.) +(Other constraints may apply as well, see the documentation for each option +for details.) -The seventh form, `nng_dialer_setopt_uint64()`, is used to configure -the 64-bit unsigned value in _u64_. -This is typically used for options -related to identifiers, network numbers, and similar. - -NOTE: Once a dialer has started, it is generally not possible to change -it's configuration. +==== `nng_dialer_setopt_uint64()` +This function is used to configure a 64-bit unsigned value, _u64_. +This is typically used for options related to identifiers, network numbers, +and similar. == RETURN VALUES -This function returns 0 on success, and non-zero otherwise. +These functions return 0 on success, and non-zero otherwise. == ERRORS @@ -110,5 +124,6 @@ This function returns 0 on success, and non-zero otherwise. <> <>, <>, +<>, <>, <> diff --git a/docs/man/nng_getopt.3.adoc b/docs/man/nng_getopt.3.adoc index 5bb151c89..bd4d4c703 100644 --- a/docs/man/nng_getopt.3.adoc +++ b/docs/man/nng_getopt.3.adoc @@ -36,14 +36,17 @@ int nng_getopt_uint64(nng_socket s, const char *opt, uint64_t *u64p); == DESCRIPTION +(((options, socket))) The `nng_getopt()` functions are used to retrieve option values for -the socket _s_. +the <> _s_. The actual options that may be retrieved in this way vary. A number of them are documented in <>. Additionally transport-specific options and protocol-specific options are documented with the transports and protocols themselves. +=== Forms + In all of these forms, the option _opt_ is retrieved from the socket _s_. The forms vary based on the type of the option they take. @@ -55,13 +58,12 @@ type is performed, so the caller must take care to use the *correct* typed form. The details of the type, size, and semantics of the option will depend on the actual option, and will be documented with the option itself. - -`nng_getopt()`:: -This function is untyped can be used to retrieve the value of any option. +==== `nng_getopt()` +This function is untyped and can be used to retrieve the value of any option. The caller must store a pointer to a buffer to receive the value in _val_, and the size of the buffer shall be stored at the location referenced by _valszp_. -+ + When the function returns, the actual size of the data copied (or that would have been copied if sufficient space were present) is stored at the location referened by _valszp_. @@ -69,38 +71,36 @@ If the caller's buffer is not large enough to hold the entire object, then the copy is truncated. Therefore the caller should check for truncation by verifyng that the returned size in _valszp_ does not exceed the original buffer size. -+ + It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. This can be used to determine the size of the buffer needed to receive the object. -`nng_getopt_bool()`:: - +==== `nng_getopt_bool()` This function is for options which take a boolean (`bool`). The value will be stored at _ivalp_. -`nng_getopt_int()`:: - +==== `nng_getopt_int()` This function is for options which take an integer (`int`). The value will be stored at _ivalp_. -`nng_getopt_ms()`:: -This function is used to retrieve time durations +==== `nng_getopt_ms()` +This function is used to retrieve time <> (such as timeouts), stored in _durp_ as a number of milliseconds. (The special value ((`NNG_DUR_INFINITE`)) means an infinite amount of time, and the special value ((`NNG_DUR_DEFAULT`)) means a context-specific default.) -`nng_getopt_ptr()`:: +==== `nng_getopt_ptr()` This function is used to retrieve a pointer, _ptr_, to structured data. The data referenced by _ptr_ is generally managed using other functions. Note that this form is somewhat special in that the object is generally not copied, but instead the *pointer* to the object is copied. -`nng_getopt_size()`:: +==== `nng_getopt_size()` This function is used to retrieve a size into the pointer _zp_, typically for buffer sizes, message maximum sizes, and similar options. -`nng_getopt_uint64()`:: +==== `nng_getopt_uint64()` This function is used to retrieve a 64-bit unsigned value into the value referenced by _u64p_. This is typically used for options related to identifiers, network @@ -108,7 +108,7 @@ numbers, and similar. == RETURN VALUES -This function returns 0 on success, and non-zero otherwise. +These functions return 0 on success, and non-zero otherwise. == ERRORS @@ -123,6 +123,7 @@ This function returns 0 on success, and non-zero otherwise. <>, <>, <>, +<>, <>, <>, <> diff --git a/docs/man/nng_listener_getopt.3.adoc b/docs/man/nng_listener_getopt.3.adoc index fde6cc0d7..6b2c2fded 100644 --- a/docs/man/nng_listener_getopt.3.adoc +++ b/docs/man/nng_listener_getopt.3.adoc @@ -22,6 +22,8 @@ nng_listener_getopt - get listener option int nng_listener_getopt(nng_listener l, const char *opt, void *val, size_t *valszp); +int nng_listener_getopt_bool(nng_listener l, const char *opt, bool *bvalp); + int nng_listener_getopt_int(nng_listener l, const char *opt, int *ivalp); int nng_listener_getopt_ms(nng_listener l, const char *opt, nng_duration *durp); @@ -35,26 +37,39 @@ int nng_listener_getopt_uint64(nng_listener l, const char *opt, uint64_t *u64p); == DESCRIPTION +(((options, listener))) The `nng_listener_getopt()` functions are used to retrieve option values for -the listener _l_. +the <> _l_. The actual options that may be retrieved in this way vary, and many are documented in <>. -Additionally some transport-specific options are documented with the -transports themselves. + +Additionally some transport-specific options and protocol-specific options +are documented with the transports and protocols themselves. + +=== Forms In all of these forms, the option _opt_ is retrieved from the listener _l_. +The forms vary based on the type of the option they take. + +TIP: Generally, it will be easier to use one of the typed versions of this +function. + +NOTE: No validation that the option is actually of the associated type is +performed, so the caller must take care to use the *correct* typed form. The details of the type, size, and semantics of the option will depend on the actual option, and will be documented with the option itself. -The first form of this function, `nng_listener_getopt()`, can be used to -retrieve the value of any option. It is untyped. The caller must store -a pointer to a buffer to receive the value in _val_, and the size of the -buffer shall be stored at the location referenced by _valszp_. +==== `nng_listener_getopt()` +This function is untyped and can be used to retrieve the value of any option. +The caller must store a pointer to a buffer to receive the value in _val_, +and the size of the buffer shall be stored at the location referenced +by _valszp_. When the function returns, the actual size of the data copied (or that would have been copied if sufficient space were present) is stored at -the location referened by _valszp_. If the caller's buffer is not large +the location referened by _valszp_. +If the caller's buffer is not large enough to hold the entire object, then the copy is truncated. Therefore the caller should validate that the returned size in _valszp_ does not exceed the original buffer size to check for truncation. @@ -63,38 +78,39 @@ It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. This can be used to determine the size of the buffer needed to receive the object. -Generally, it will be easier to use one of the typed forms instead. Note -however that no validation that the option is actually of the associated -type is performed, so the caller must take care to use the *correct* typed -form. +==== `nng_listener_getopt_bool()` +This function is for options which take a boolean (`bool`). +The value will be stored at _ivalp_. -The second form, `nng_listener_getopt_int()`, -is for options which take an integer (or boolean). The value will -be stored at _ivalp_. For booleans the value will be eiher 0 (false) or 1 (true). +==== `nng_listener_getopt_int()` +This function is for options which take an integer (`int`). +The value will be stored at _ivalp_. -The third form, `nng_listener_getopt_ms()`, is used to retrieve time durations +==== `nng_listener_getopt_ms()` +This function is used to retrieve time <> (such as timeouts), stored in _durp_ as a number of milliseconds. -(The special value `NNG_DUR_INFINITE` means an infinite amount of time, and -the special value `NNG_DUR_DEFAULT` means a context-specific default.) +(The special value ((`NNG_DUR_INFINITE`)) means an infinite amount of time, and +the special value ((`NNG_DUR_DEFAULT`)) means a context-specific default.) -The fourth form, `nng_listener_getopt_ptr()`, is used to retrieve a -pointer _ptr_ to structured data. The data referenced by _ptr_ is -generally managed using other functions. +==== `nng_listener_getopt_ptr()` +This function is used to retrieve a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed using other functions. Note that this form is somewhat special in that the object is generally not copied, but instead the *pointer* to the object is copied. -The fifth form, `nng_listener_getopt_size()`, is used to retrieve a size -into the pointer _zp_, typically for buffer sizes, message maximum sizes, and -similar options. +==== `nng_listener_getopt_size()` +This function is used to retrieve a size into the pointer _zp_, +typically for buffer sizes, message maximum sizes, and similar options. -The sixth form, `nng_listener_getopt_uint64()`, is used to retrieve a -64-bit unsigned value into the value referenced by _u64p_. -This is typically used for options -related to identifiers, network numbers, and similar. +==== `nng_listener_getopt_uint64()` +This function is used to retrieve a 64-bit unsigned value into the value +referenced by _u64p_. +This is typically used for options related to identifiers, network +numbers, and similar. == RETURN VALUES -This function returns 0 on success, and non-zero otherwise. +These functions return 0 on success, and non-zero otherwise. == ERRORS diff --git a/docs/man/nng_listener_setopt.3.adoc b/docs/man/nng_listener_setopt.3.adoc index 5f95b0991..93cae9ab0 100644 --- a/docs/man/nng_listener_setopt.3.adoc +++ b/docs/man/nng_listener_setopt.3.adoc @@ -37,60 +37,76 @@ int nng_listener_setopt_uint64(nng_listener l, const char *opt, uint64_t u64); == DESCRIPTION +(((options, listener))) The `nng_listener_setopt()` functions are used to configure options for -the listener _l_. The actual options that may be configured in this way +the <> _l_. +The actual options that may be configured in this way vary, and many are documented in <>. -Additionally some transport-specific options are documented with the -transports themselves. + +Additionally some transport-specific options and protocol-specific options +are documented with the transports and protocols themselves. + +NOTE: Once a listener has started, it is generally not possible to change +it's configuration. + +=== Forms In all of these forms, the option _opt_ is configured on the listener _l_. The details of the type, size, and semantics of the option will depend on the actual option, and will be documented with the option itself. -The first form of this function, `nng_listener_setopt()`, can be used to -configure any arbitrary data. -The _val_ pointer addresses the data to copy, and _valsz_ is the -size of the objected located at _val_. +TIP: Generally, it will be easier to use one of the typed forms instead. -Generally, it will be easier to use one of the typed forms instead. +NOTE: No validation that the option is actually of the associated +type is performed, so the caller must take care to use the *correct* typed form. -The second form, `nng_listener_setopt_int()`, -is for options which take an integer (or boolean). The _ival_ -is passed to the option. For booleans pass either 0 (false) or 1 (true). - -The third form, `nng_listener_setopt_ms()`, is used to configure time durations -(such as timeouts). -The duration _dur_ is an integer number of milliseconds. (The special value -`NNG_DUR_INFINITE` means an infinite amount of time.) +==== `nng_listener_setopt()` +This function is untyped, and can be used to configure any arbitrary data. +The _val_ pointer addresses the data to copy, and _valsz_ is the +size of the objected located at _val_. -The fourth form, `nng_listener_setopt_ptr()`, is used to pass a -pointer _ptr_ to structured data. The data referenced by _ptr_ is -generally managed by other functions. -For example, TLS configuration objects -(<>) can be passed this way. +==== `nng_listener_setopt_bool()` +This function is for options which take a boolean (`bool`). +The _bval_ is passed to the option. + +==== `nng_listener_setopt_int()` +This function is for options which take an integer (`int`). +The _ival_ is passed to the option. + +==== `nng_listener_setopt_ms()` +This function is used to configure time durations (such as timeouts) using +type <>. +The duration _dur_ is an integer number of milliseconds. + +==== `nng_listener_setopt_ptr()` +This function is used to pass a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed by other functions. +For example, TLS configuration objects created with +(<>) +can be passed this way. Note that this form is somewhat special in that the object is generally not copied, but instead the *pointer* to the object is copied. -The fifth form, `nng_listener_setopt_size()`, is used to pass a size -specified by _z_, typically for buffer sizes, message maximum sizes, and -similar options. +==== `nng_listener_setopt_size()` +This function is used to configure a size, _z_, typically for buffer sizes, +message maximum sizes, and similar options. -The sixth form, `nng_listener_setopt_string()`, is used to pass a string -_str_. Strings passed this way must be legal UTF-8 or ASCII strings, terminated -with a `NUL` (`\0`) byte. (Other constraints may apply as well, see the -documentation for _opt_ for details.) +==== `nng_listener_setopt_string()` +This function is used to pass configure a string, _str_. +Strings passed this way must be legal UTF-8 or ASCII strings, terminated +with a `NUL` (`\0`) byte. +(Other constraints may apply as well, see the documentation for each option +for details.) -The seventh form, `nng_listener_setopt_uint64()`, is used to configure -the 64-bit unsigned value in _u64_. This is typically used for options -related to identifiers, network numbers, and similar. - -NOTE: Once a listener has started, it is generally not possible to change -it's configuration. +==== `nng_listener_setopt_uint64()` +This function is used to configure a 64-bit unsigned value, _u64_. +This is typically used for options related to identifiers, network numbers, +and similar. == RETURN VALUES -This function returns 0 on success, and non-zero otherwise. +These functions return 0 on success, and non-zero otherwise. == ERRORS diff --git a/docs/man/nng_pipe_getopt.3.adoc b/docs/man/nng_pipe_getopt.3.adoc index 598de0536..3198fc211 100644 --- a/docs/man/nng_pipe_getopt.3.adoc +++ b/docs/man/nng_pipe_getopt.3.adoc @@ -16,31 +16,35 @@ nng_pipe_getopt - get pipe option == SYNOPSIS [source, c] ------------ +---- #include int nng_pipe_getopt(nng_pipe p, const char *opt, void *val, size_t *valszp); +int nng_pipe_getopt_bool(nng_pipe p, const char *opt, int *bvalp); + int nng_pipe_getopt_int(nng_pipe p, const char *opt, int *ivalp); int nng_pipe_getopt_ms(nng_pipe p, const char *opt, nng_duration *durp); +int nng_dialer_getopt_ptr(nng_pipe p, const char *opt, void **ptr); + int nng_pipe_getopt_size(nng_pipe p, const char *opt, size_t *zp); int nng_pipe_getopt_uint64(nng_pipe p, const char *opt, uint64_t *u64p); ------------ +---- == DESCRIPTION +(((options, pipe))) The `nng_pipe_getopt()` functions are used to retrieve option values for the <> _p_. The actual options that may be retrieved in this way vary, and many are documented in <>. -Additionally some transport-specific options are documented with the -transports themselves, and some protocol-specific options are documented -with the protocol. +Additionally some transport-specific options and protocol-specific options are +documented with the transports andp protocols themselves. -NOTE: All "options" on a pipe are read-only values, and intended to +NOTE: All "`options`" on a pipe are read-only values, and intended to facilitate understanding the identity of an associated peer. Modification of options must be done on the listener or dialer using either <> or @@ -49,12 +53,14 @@ Modification of options must be done on the listener or dialer using either Any option that is set on a dialer or listener will normally be retrievable from pipes created by that dialer or listener. +=== Forms + In all of these forms, the option _opt_ is retrieved from the pipe _p_. The details of the type, size, and semantics of the option will depend on the actual option, and will be documented with the option itself. -=== `nng_pipe_getopt()`:: +==== `nng_pipe_getopt()` This is untyped, and can be used to retrieve the value of any option. A pointer to a buffer to receive the value in _val_, and the size of the @@ -76,42 +82,44 @@ TIP: Generally, it will be easier to use one of the typed forms instead. Note however that no validation that the option is actually of the associated type is performed, so the caller must take care to use the *correct* typed form. -=== `nng_pipe_getopt_int()`:: +==== `nng_pipe_getopt_bool()` + +This function is for options which take a boolean (`bool`). +The value will be stored at _bvalp_. + +==== `nng_pipe_getopt_int()` This function is for options which take an integer (`int`) or boolean (`bool`). The value will be stored at _ivalp_. For booleans the value will be eiher 0 (`false`) or 1 (`true`). -=== `nng_pipe_getopt_ms()`:: +==== `nng_pipe_getopt_ms()` This function is used to retrieve time durations -(<>) in milliseconds, which are stored in _durp_. -=== `nng_pipe_getopt_size()`:: +==== `nng_pipe_getopt_ptr()` +This function is used to retrieve a pointer, _ptr_, to structured data. +The data referenced by _ptr_ is generally managed using other functions. +Note that this form is somewhat special in that the object is generally +not copied, but instead the *pointer* to the object is copied. + +==== `nng_pipe_getopt_size()` This function is used to retrieve a size into the pointer _zp_, typically for buffer sizes, message maximum sizes, and similar options. -=== `nng_pipe_getopt_uint64()`:: +==== `nng_pipe_getopt_uint64()` This function is used to retriev a 64-bit unsigned value into the value referenced by _u64p_. This is typically used for options related to identifiers, network numbers, and similar. -// XXX: nng_pipe_getopt_ptr is not supported, and would carry some risks, -// as the pipe may not survive, and the endpoint options may not survive, -// leading to questions about pointer validity. -// The last form, `nng_pipe_getopt_ptr()`, is used to retrieve a -// pointer _ptr_ to structured data. The data referenced by _ptr_ is -// generally managed using other functions. -// Note that this form is somewhat special in that the object is generally -// not copied, but instead the *pointer* to the object is copied. - == RETURN VALUES -This function returns 0 on success, and non-zero otherwise. +These functions return 0 on success, and non-zero otherwise. == ERRORS diff --git a/docs/man/nng_setopt.3.adoc b/docs/man/nng_setopt.3.adoc index 201181ccd..915fb5ded 100644 --- a/docs/man/nng_setopt.3.adoc +++ b/docs/man/nng_setopt.3.adoc @@ -47,6 +47,8 @@ A number of them are documented in <>. Additionally some transport-specific and protocol-specific options are documented with the transports and protocols themselves. +=== Forms + The details of the type, size, and semantics of the option will depend on the actual option, and will be documented with the option itself. @@ -56,25 +58,25 @@ of this function. NOTE: No validation that the option is actually of the associated type is performed, so the caller must take care to use the *correct* typed form. -`nng_setopt()`:: +==== `nng_setopt()` This function is untyped, and can be used to configure any arbitrary data. The _val_ pointer addresses the data to copy, and _valsz_ is the size of the objected located at _val_. -`nng_setopt_bool()`:: +==== `nng_setopt_bool()` This function is for options which take a boolean (`bool`). The _bval_ is passed to the option. -`nng_setopt_int()`:: +==== `nng_setopt_int()` This function is for options which take an integer (`int`). The _ival_ is passed to the option. -`nng_setopt_ms()`:: +==== `nng_setopt_ms()` This function is used to configure time durations (such as timeouts) using type <>. The duration _dur_ is an integer number of milliseconds. -`nng_setopt_ptr()`:: +==== `nng_setopt_ptr()` This function is used to pass a pointer, _ptr_, to structured data. The data referenced by _ptr_ is generally managed by other functions. For example, TLS configuration objects created with @@ -83,25 +85,25 @@ can be passed this way. Note that this form is somewhat special in that the object is generally not copied, but instead the *pointer* to the object is copied. -`nng_setopt_size()`:: +==== `nng_setopt_size()` This function is used to configure a size, _z_, typically for buffer sizes, message maximum sizes, and similar options. -`nng_setopt_string()`:: +==== `nng_setopt_string()` This function is used to pass configure a string, _str_. Strings passed this way must be legal UTF-8 or ASCII strings, terminated with a `NUL` (`\0`) byte. (Other constraints may apply as well, see the documentation for each option for details.) -`nng_setopt_uint64()`:: +==== `nng_setopt_uint64()` This function is used to configure a 64-bit unsigned value, _u64_. This is typically used for options related to identifiers, network numbers, and similar. == RETURN VALUES -This function returns 0 on success, and non-zero otherwise. +These functions return 0 on success, and non-zero otherwise. == ERRORS diff --git a/docs/man/nng_url_free.3.adoc b/docs/man/nng_url_free.3.adoc index 62e3396ed..a210d0166 100644 --- a/docs/man/nng_url_free.3.adoc +++ b/docs/man/nng_url_free.3.adoc @@ -16,11 +16,11 @@ nng_url_free - free a URL structure == SYNOPSIS [source, c] ------------ +---- #include void nng_url_free(nng_url *url); ------------ +---- == DESCRIPTION diff --git a/docs/man/nng_url_parse.3.adoc b/docs/man/nng_url_parse.3.adoc index b109eecb2..699735dcf 100644 --- a/docs/man/nng_url_parse.3.adoc +++ b/docs/man/nng_url_parse.3.adoc @@ -16,11 +16,11 @@ nng_url_parse - create URL structure from a string == SYNOPSIS [source, c] ------------ +---- #include int nng_url_parse(nng_url **urlp, const char *str); ------------ +---- == DESCRIPTION