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_pipe_getopt.3.adoc | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

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

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