document tls_config_error(3) RETURN VALUES, improve what is said

about tls_error(3), and warn about some traps;
OK jmc@

1 files changed, 27 insertions, 2 deletions

diff --git a/src/lib/libtls/man/tls_init.3 b/src/lib/libtls/man/tls_init.3
index 36d2e29084..b17bb814fe 100644
--- a/src/lib/libtls/man/tls_init.3
+++ b/src/lib/libtls/man/tls_init.3
@@ -1,7 +1,8 @@
-.\" $OpenBSD: tls_init.3,v 1.3 2017/01/28 00:59:36 schwarze Exp $
+.\" $OpenBSD: tls_init.3,v 1.4 2017/02/20 13:09:15 schwarze Exp $
 .\"
 .\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
 .\" Copyright (c) 2016 Joel Sing <jsing@openbsd.org>
+.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +16,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: January 28 2017 $
+.Dd $Mdocdate: February 20 2017 $
 .Dt TLS_INIT 3
 .Os
 .Sh NAME
@@ -107,6 +108,15 @@ returns 0 on success or -1 on error.
 returns
 .Dv NULL
 on error or an out of memory condition.
+.Pp
+.Fn tls_config_error
+returns
+.Dv NULL
+if no error occured with
+.Fa config
+at all, or if memory allocation failed while trying to assemble the
+string describing the most recent error related to
+.Fa config .
 .Sh SEE ALSO
 .Xr tls_accept_socket 3 ,
 .Xr tls_client 3 ,
@@ -142,3 +152,18 @@ appeared in
 .Pp
 Many others contributed to various parts of the library; see the
 individual manual pages for more information.
+.Sh CAVEATS
+The function
+.Fn tls_config_error
+returns an internal pointer.
+It must not be freed by the application, or a double free error
+will occur.
+The pointer will become invalid when the next error occurs with
+.Fa config .
+Consequently, if the application may need the message at a later
+time, it has to copy the string before calling the next
+.Sy libtls
+function involving
+.Fa config ,
+or a segmentation fault or read access to unintended data is the
+likely result.