From 6df40cb6eea9a4220d61c4c927ce5a857a12a338 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Tue, 20 Mar 2018 18:38:54 -0700
Subject: fixes #301 String option handling for getopt

---
 docs/man/nng_getopt.3.adoc | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

(limited to 'docs/man/nng_getopt.3.adoc')

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)>>,
-- 
cgit v1.2.3-70-g09d2