fixes #301 String option handling for getopt

12 files changed, 185 insertions, 33 deletions

diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 66b00698..c5c345f6 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -31,7 +31,9 @@ The following common functions exist in _libnng_.
 |===
 |<<nng_alloc.3#,nng_alloc()>>|allocate memory
 |<<nng_free.3#,nng_free()>>|free memory
+|<<nng_strdup.3#,nng_strdup()>>|duplicate string
 |<<nng_strerror.3#,nng_strerror()>>|return an error description
+|<<nng_strfree.3#,nng_strfree()>>|free string
 |<<nng_version.3#,nng_version()>>|report library version
 |===
 
diff --git a/docs/man/nng_alloc.3.adoc b/docs/man/nng_alloc.3.adoc
index 7d7adf07..a43140d1 100644
--- a/docs/man/nng_alloc.3.adoc
+++ b/docs/man/nng_alloc.3.adoc
@@ -33,17 +33,19 @@ case it can be directly passed to <<nng_send.3#,`nng_send()`>> using
 the flag `NNG_FLAG_ALLOC`.  Alternatively, it can be freed when no
 longer needed using <<nng_free.3#,`nng_free()`>>.
 
-WARNING: Do not use the system `free()` function to release this memory.
+IMPORTANT: Do not use the system `free()` function to release this memory.
 On some platforms this may work, but it is not guaranteed and may lead
 to a crash or other undesirable and unpredictable behavior.
 
 == RETURN VALUES
 
-This function returns 0 on success, and non-zero otherwise.
+This function returns a pointer to the allocated memory on success,
+and `NULL` otherwise.
 
 == ERRORS
 
-`NNG_ENOMEM`:: Insufficient free memory exists.
+No errors are returned, but a `NULL` return value should be
+treated the same as `NNG_ENOMEM`.
 
 == SEE ALSO
 
diff --git a/docs/man/nng_dialer_getopt.3.adoc b/docs/man/nng_dialer_getopt.3.adoc
index 3fde89d6..bdabc5d9 100644
--- a/docs/man/nng_dialer_getopt.3.adoc
+++ b/docs/man/nng_dialer_getopt.3.adoc
@@ -33,6 +33,8 @@ int nng_dialer_getopt_size(nng_dialer d, const char *opt, size_t *zp);
 
 int nng_dialer_getopt_sockaddr(nng_dialer d, const char *opt, nng_sockaddr *sap);
 
+int nng_dialer_getopt_string(nng_dialer d, const char *opt, char **strp);
+
 int nng_dialer_getopt_uint64(nng_dialer d, const char *opt, uint64_t *u64p);
 ----
 
@@ -52,15 +54,12 @@ are documented with the transports and protocols themselves.
 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.
 
+TIP: Generally, it will be easier to use one of the typed versions of this
+function.
+
 ==== `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_,
@@ -107,6 +106,13 @@ typically for buffer sizes, message maximum sizes, and similar options.
 This function is used to retrieve an <<nng_sockaddr.5#,`nng_sockaddr`>>
 into the value referenced by _sap_.
 
+==== `nng_dialer_getopt_string()`
+
+This function is used to retrieve a string into _strp_.
+This string is created from the source using <<nng_strdup.3#,`nng_strdup()`>>
+and consequently must be freed by the caller using
+<<nng_strfree.3#,`nng_strfree()`>> when it is no longer needed.
+
 ==== `nng_dialer_getopt_uint64()`
 This function is used to retrieve a 64-bit unsigned value into the value
 referenced by _u64p_.
@@ -119,7 +125,10 @@ These functions returns 0 on success, and non-zero otherwise.
 
 == ERRORS
 
+`NNG_EBADTYPE`:: Incorrect type for option.
 `NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer.
+`NNG_EINVAL`:: Size of destination _val_ too small for object.
+`NNG_ENOMEM`:: Insufficient memory exists.
 `NNG_ENOTSUP`:: The option _opt_ is not supported.
 `NNG_EWRITEONLY`:: The option _opt_ is write-only.
 
@@ -127,7 +136,9 @@ These functions returns 0 on success, and non-zero otherwise.
 
 <<nng_dialer_create.3#,nng_dialer_create(3)>>
 <<nng_dialer_setopt.3#,nng_dialer_setopt(3)>>
+<<nng_strdup.3#,nng_strdup(3)>>,
 <<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_strfree.3#,nng_strfree(3)>>,
 <<nng_dialer.5#,nng_dialer(5)>>,
 <<nng_duration.5#,nng_duration(5)>>,
 <<nng_options.5#,nng_options(5)>>,
diff --git a/docs/man/nng_dialer_setopt.3.adoc b/docs/man/nng_dialer_setopt.3.adoc
index 1bec71b2..330657d0 100644
--- a/docs/man/nng_dialer_setopt.3.adoc
+++ b/docs/man/nng_dialer_setopt.3.adoc
@@ -60,9 +60,6 @@ on the actual option, and will be documented with the option itself.
 
 TIP: 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.
-
 ==== `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
@@ -112,6 +109,7 @@ These functions return 0 on success, and non-zero otherwise.
 
 == ERRORS
 
+`NNG_EBADTYPE`:: Incorrect type for option.
 `NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer.
 `NNG_EINVAL`:: The value being passed is invalid.
 `NNG_ENOTSUP`:: The option _opt_ is not supported.
diff --git a/docs/man/nng_free.3.adoc b/docs/man/nng_free.3.adoc
index c5588a1c..d17f3da5 100644
--- a/docs/man/nng_free.3.adoc
+++ b/docs/man/nng_free.3.adoc
@@ -28,10 +28,10 @@ The `nng_free()` function deallocates a memory region of size _size_,
 that was previously allocated by <<nng_alloc.3#,`nng_alloc()`>> or
 <<nng_recv.3#,`nng_recv()`>> with the `NNG_FLAG_ALLOC` flag.
 
-WARNING: It is very important that _size_ match the allocation size
+IMPORTANT: It is very important that _size_ match the allocation size
 used to allocate the memory.
 
-WARNING: Do not attempt to use this function to deallocate memory
+IMPORTANT: Do not attempt to use this function to deallocate memory
 obtained by a call to the system `malloc()` or `calloc()` functions,
 or the {cpp} `new` operator.
 Doing so may result in unpredictable
diff --git a/docs/man/nng_getopt.3.adoc b/docs/man/nng_getopt.3.adoc
index bd4d4c70..af61132c 100644
--- a/docs/man/nng_getopt.3.adoc
+++ b/docs/man/nng_getopt.3.adoc
@@ -31,6 +31,8 @@ int nng_getopt_ptr(nng_socket s, const char *opt, void **ptr);
 
 int nng_getopt_size(nng_socket s, const char *opt, size_t *zp);
 
+int nng_getopt_string(nng_socket s, const char *opt, char **strp);
+
 int nng_getopt_uint64(nng_socket s, const char *opt, uint64_t *u64p);
 -----------
 
@@ -50,14 +52,11 @@ documented with the transports and protocols themselves.
 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.
 
-TIP: 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 details of the type, size, and semantics of the option will depend
 on the actual option, and will be documented with the option itself.
 
+TIP: Generally, it will be easier to use one of the typed forms instead.
+
 ==== `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_,
@@ -100,6 +99,12 @@ not copied, but instead the *pointer* to the object is copied.
 This function is used to retrieve a size into the pointer _zp_,
 typically for buffer sizes, message maximum sizes, and similar options.
 
+==== `nng_getopt_string()`
+This function is used to retrieve a string into _strp_.
+This string is created from the source using <<nng_strdup.3#,`nng_strdup()`>>
+and consequently must be freed by the caller using
+<<nng_strfree.3#,`nng_strfree()`>> when it is no longer needed.
+
 ==== `nng_getopt_uint64()`
 This function is used to retrieve a 64-bit unsigned value into the value
 referenced by _u64p_.
@@ -112,7 +117,10 @@ These functions return 0 on success, and non-zero otherwise.
 
 == ERRORS
 
+`NNG_EBADTYPE`:: Incorrect type for option.
 `NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket.
+`NNG_EINVAL`:: Size of destination _val_ too small for object.
+`NNG_ENOMEM`:: Insufficient memory exists.
 `NNG_ENOTSUP`:: The option _opt_ is not supported.
 `NNG_EWRITEONLY`:: The option _opt_ is write-only.
 
@@ -122,7 +130,9 @@ These functions return 0 on success, and non-zero otherwise.
 <<nng_listener_getopt.3#,nng_listener_getopt(3)>>,
 <<nng_pipe_getopt.3#,nng_pipe_getopt(3)>>,
 <<nng_setopt.3#,nng_setopt(3)>>,
+<<nng_strdup.3#,nng_strdup(3)>>,
 <<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_strfree.3#,nng_strfree(3)>>,
 <<nng_duration.5#,nng_duration(5)>>,
 <<nng_options.5#,nng_options(5)>>,
 <<nng_socket.5#,nng_socket(5)>>,
diff --git a/docs/man/nng_listener_getopt.3.adoc b/docs/man/nng_listener_getopt.3.adoc
index 1bafd1d6..3fe79868 100644
--- a/docs/man/nng_listener_getopt.3.adoc
+++ b/docs/man/nng_listener_getopt.3.adoc
@@ -33,6 +33,8 @@ int nng_listener_getopt_size(nng_listener l, const char *opt, size_t *zp);
 
 int nng_listener_getopt_sockaddr(nng_listener l, const char *opt, nng_sockaddr *sap);
 
+int nng_listener_getopt_string(nng_listener l, const char *opt, char **strp);
+
 int nng_listener_getopt_uint64(nng_listener l, const char *opt, uint64_t *u64p);
 ----
 
@@ -52,15 +54,12 @@ are documented with the transports and protocols themselves.
 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.
 
+TIP: Generally, it will be easier to use one of the typed versions of this
+function.
+
 ==== `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_,
@@ -105,6 +104,12 @@ typically for buffer sizes, message maximum sizes, and similar options.
 This function is used to retrieve an <<nng_sockaddr.5#,`nng_sockaddr`>>
 into the value referenced by _sap_.
 
+==== `nng_listener_getopt_string()`
+This function is used to retrieve a string into _strp_.
+This string is created from the source using <<nng_strdup.3#,`nng_strdup()`>>
+and consequently must be freed by the caller using
+<<nng_strfree.3#,`nng_strfree()`>> when it is no longer needed.
+
 ==== `nng_listener_getopt_uint64()`
 This function is used to retrieve a 64-bit unsigned value into the value
 referenced by _u64p_.
@@ -117,7 +122,10 @@ These functions return 0 on success, and non-zero otherwise.
 
 == ERRORS
 
+`NNG_EBADTYPE`:: Incorrect type for option.
 `NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener.
+`NNG_EINVAL`:: Size of destination _val_ too small for object.
+`NNG_ENOMEM`:: Insufficient memory exists.
 `NNG_ENOTSUP`:: The option _opt_ is not supported.
 `NNG_EWRITEONLY`:: The option _opt_ is write-only.
 
@@ -127,7 +135,9 @@ These functions return 0 on success, and non-zero otherwise.
 <<nng_listener_create.3#,nng_listener_create(3)>>
 <<nng_listener_setopt.3#,nng_listener_setopt(3)>>
 <<nng_getopt.3#,nng_getopt(3)>>,
+<<nng_strdup.3#,nng_strdup(3)>>,
 <<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_strfree.3#,nng_strfree(3)>>,
 <<nng_duration.5#,nng_duration(5)>>,
 <<nng_listener.5#,nng_listener(5)>>,
 <<nng_options.5#,nng_options(5)>>,
diff --git a/docs/man/nng_listener_setopt.3.adoc b/docs/man/nng_listener_setopt.3.adoc
index 03a33a57..d24a4f06 100644
--- a/docs/man/nng_listener_setopt.3.adoc
+++ b/docs/man/nng_listener_setopt.3.adoc
@@ -58,9 +58,6 @@ on the actual option, and will be documented with the option itself.
 
 TIP: 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.
-
 ==== `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
@@ -110,6 +107,7 @@ These functions return 0 on success, and non-zero otherwise.
 
 == ERRORS
 
+`NNG_EBADTYPE`:: Incorrect type for option.
 `NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener.
 `NNG_EINVAL`:: The value being passed is invalid.
 `NNG_ENOTSUP`:: The option _opt_ is not supported.
diff --git a/docs/man/nng_pipe_getopt.3.adoc b/docs/man/nng_pipe_getopt.3.adoc
index fd607198..66216a73 100644
--- a/docs/man/nng_pipe_getopt.3.adoc
+++ b/docs/man/nng_pipe_getopt.3.adoc
@@ -31,6 +31,8 @@ int nng_dialer_getopt_ptr(nng_pipe p, const char *opt, void **ptr);
 
 int nng_pipe_getopt_sockaddr(nng_pipe p, const char *opt, nng_sockaddr *sap);
 
+int nng_pipe_getopt_string(nng_pipe p, const char *opt, char **strp);
+
 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);
@@ -81,8 +83,6 @@ This can be used to determine the size of the buffer needed to receive
 the object.
 
 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_bool()`
 
@@ -117,6 +117,13 @@ typically for buffer sizes, message maximum sizes, and similar options.
 This function is used to retrieve an <<nng_sockaddr.5#,`nng_sockaddr`>>
 into _sap_.
 
+==== `nng_pipe_getopt_string()`
+
+This function is used to retrieve a string into _strp_.
+This string is created from the source using <<nng_strdup.3#,`nng_strdup()`>>
+and consequently must be freed by the caller using
+<<nng_strfree.3#,`nng_strfree()`>> when it is no longer needed.
+
 ==== `nng_pipe_getopt_uint64()`
 
 This function is used to retriev a 64-bit unsigned value into the value
@@ -130,8 +137,11 @@ These functions return 0 on success, and non-zero otherwise.
 
 == ERRORS
 
+`NNG_EBADTYPE`:: Incorrect type for option.
 `NNG_ECLOSED`:: Parameter _p_ does not refer to an open pipe.
 `NNG_ENOTSUP`:: The option _opt_ is not supported.
+`NNG_ENOMEM`:: Insufficient memory exists.
+`NNG_EINVAL`:: Size of destination _val_ too small for object.
 `NNG_EWRITEONLY`:: The option _opt_ is write-only.
 
 == SEE ALSO
@@ -140,7 +150,9 @@ These functions return 0 on success, and non-zero otherwise.
 <<nng_getopt.3#,nng_getopt(3)>>,
 <<nng_listener_setopt.3#,nng_listener_setopt(3)>>
 <<nng_msg_get_pipe.3#,nng_msg_get_pipe(3)>>
+<<nng_strdup.3#,nng_strdup(3)>>,
 <<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_strfree.3#,nng_strfree(3)>>,
 <<nng_duration.5#,nng_duration(5)>>,
 <<nng_options.5#,nng_options(5)>>,
 <<nng_pipe.5#,nng_pipe(5)>>,
diff --git a/docs/man/nng_setopt.3.adoc b/docs/man/nng_setopt.3.adoc
index 915fb5de..91e54225 100644
--- a/docs/man/nng_setopt.3.adoc
+++ b/docs/man/nng_setopt.3.adoc
@@ -55,9 +55,6 @@ on the actual option, and will be documented with the option itself.
 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.
-
 ==== `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
diff --git a/docs/man/nng_strdup.3.adoc b/docs/man/nng_strdup.3.adoc
new file mode 100644
index 00000000..23e23a43
--- /dev/null
+++ b/docs/man/nng_strdup.3.adoc
@@ -0,0 +1,55 @@
+= nng_strdup(3)
+//
+// 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_strdup - duplicate string
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+char *nng_strdup(const char *src);
+----
+
+== DESCRIPTION
+
+The `nng_strdup()` duplicates the string _src_ and returns it.
+
+This is logically equiavlent to using <<nng_alloc.3#,`nng_alloc()`>>
+to allocate a region of memory of `strlen(s) + 1` bytes, and then
+using `strcpy()` to copy the string into the destination before
+returning it.
+
+The returned string should be deallocated with
+<<nng_strfree.3#,`nng_strfree()`>>, or may be deallocated using the
+<<nng_free.3#,`nng_free()`>> using the length of the returned string plus
+one (for the `NUL` terminating byte).
+
+IMPORTANT: Do not use the system `free()` or similar functions to deallocate
+the string, since those may use a different memory arena!
+
+== RETURN VALUES
+
+This function returns the new string on success, and `NULL` on failure.
+
+== ERRORS
+
+No errors are returned, but a `NULL` return value should be
+treated the same as `NNG_ENOMEM`.
+
+== SEE ALSO
+
+<<nng_alloc.3#,nng_alloc(3)>>,
+<<nng_free.3#,nng_free(3)>>,
+<<nng.7#,nng(7)>>
diff --git a/docs/man/nng_strfree.3.adoc b/docs/man/nng_strfree.3.adoc
new file mode 100644
index 00000000..2e6569a8
--- /dev/null
+++ b/docs/man/nng_strfree.3.adoc
@@ -0,0 +1,57 @@
+= nng_strfree(3)
+//
+// 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_free - free memory
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+void nng_strfree(char *str);
+----
+
+== DESCRIPTION
+
+The `nng_strfree()` function deallocates the string _str_.
+This is equivalent to using <<nng_free.3#,`nng_free()`>> with
+the length of _str_ plus one (for the `NUL` terminating byte) as
+the size.
+
+IMPORTANT: This should only be used with strings that were allocated
+by <<nng_strdup.3#,`nng_strdup()`>> or
+<<nng_alloc.3#,`nng_alloc()`>>.
+In all cases, the allocation size of the string must be the same
+as `strlen(__str__) + 1`.
+
+IMPORTANT: Consequently, if the a string created with
+<<nng_strdup.3#,`nng_strdup()`>> is modified to be shorter, then
+it is incorrect to call this function.
+(The <<nng_free.3#,`nng_free()`>> function can be used instead in that
+case, using the length of the original string plus one for the size.)
+
+== RETURN VALUES
+
+None.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_alloc.3#,nng_alloc(3)>>,
+<<nng_free.3#,nng_free(3)>>,
+<<nng_strdup.3#,nng_strdup(3)>>,
+<<nng.7#,nng(7)>>