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

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

2 files changed, 59 insertions, 6 deletions

diff --git a/lib/libtls/man/tls_init.3 b/lib/libtls/man/tls_init.3
index 36d2e29084d..b17bb814fe1 100644
--- a/lib/libtls/man/tls_init.3
+++ b/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.
diff --git a/lib/libtls/man/tls_read.3 b/lib/libtls/man/tls_read.3
index e9903610175..a7faebaea78 100644
--- a/lib/libtls/man/tls_read.3
+++ b/lib/libtls/man/tls_read.3
@@ -1,9 +1,10 @@
-.\" $OpenBSD: tls_read.3,v 1.3 2017/01/28 00:59:36 schwarze Exp $
+.\" $OpenBSD: tls_read.3,v 1.4 2017/02/20 13:09:15 schwarze Exp $
 .\"
 .\" Copyright (c) 2014, 2015 Ted Unangst <tedu@openbsd.org>
 .\" Copyright (c) 2015 Doug Hogan <doug@openbsd.org>
 .\" Copyright (c) 2015 Joel Sing <jsing@openbsd.org>
 .\" Copyright (c) 2015 Bob Beck <beck@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
@@ -17,7 +18,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_READ 3
 .Os
 .Sh NAME
@@ -106,8 +107,20 @@ return 0 on success or -1 on error.
 .Fn tls_error
 returns
 .Dv NULL
-if no error occurred or the first place, or if memory allocation
-failed while trying to assemble the string describing the error.
+if no error occurred with
+.Fa ctx
+during or since the last call to
+.Fn tls_handshake ,
+.Fn tls_read ,
+.Fn tls_write ,
+.Fn tls_close ,
+or
+.Fn tls_reset
+involving
+.Fa ctx ,
+or if memory allocation failed while trying to assemble the string
+describing the most recent error related to
+.Fa ctx .
 .Pp
 The
 .Fn tls_read ,
@@ -215,3 +228,18 @@ appeared in
 .An Joel Sing Aq Mt jsing@openbsd.org
 with contributions from
 .An Bob Beck Aq Mt beck@openbsd.org
+.Sh CAVEATS
+The function
+.Fn tls_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 ctx .
+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 ctx ,
+or a segmentation fault or read access to unintended data is the
+likely result.