Mark ERR_add_error_data and ERR_add_error_vdata as not for internal use,

and document ERR_asprintf_error_data as their replacement.
ok jsing@, ingo@

3 files changed, 68 insertions, 4 deletions

diff --git a/lib/libcrypto/man/ERR_asprintf_error_data.3 b/lib/libcrypto/man/ERR_asprintf_error_data.3
new file mode 100644
index 00000000000..6481da4750c
--- /dev/null
+++ b/lib/libcrypto/man/ERR_asprintf_error_data.3
@@ -0,0 +1,55 @@
+.\" $OpenBSD: ERR_asprintf_error_data.3,v 1.1 2017/02/20 23:21:19 beck Exp $
+.\"
+.\" Copyright (c) 2017 Bob Beck <beck@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
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.Dd $Mdocdate: February 20 2017 $
+.Dt ERR_ASPRINTF_ERROR_DATA 3
+.Os
+.Sh NAME
+.Nm ERR_asprintf_error_data
+.Nd record a LibreSSL error using a formatted string.
+.Sh SYNOPSIS
+.In openssl/err.h
+.Ft void
+.Fo ERR_asprintf_error_data
+.Fa "char * format"
+.Fa ...
+.Fc
+.Sh DESCRIPTION
+.Nm
+builds a string using
+.Xr asprintf 3
+called with the provided
+.Ar format
+and arguments.
+The resulting string is then associated with the error code that was most
+recently added.
+If
+.Xr asprintf 3
+fails, the string "malloc failed" is associated instead.
+.Pp
+.Nm
+is intended to be used instead of the OpenSSL functions
+.Xr ERR_add_error_data 3
+and
+.Xr ERR_add_error_vdata 3 .
+.Sh SEE ALSO
+.Xr ERR 3 ,
+.Xr ERR_put_error 3 ,
+.Xr printf 3
+.Sh HISTORY
+.Nm
+appeared in
+.Ox 5.6
+and is available in all versions of LibreSSL.
diff --git a/lib/libcrypto/man/ERR_put_error.3 b/lib/libcrypto/man/ERR_put_error.3
index 2b41bedea3a..3011e16df4b 100644
--- a/lib/libcrypto/man/ERR_put_error.3
+++ b/lib/libcrypto/man/ERR_put_error.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ERR_put_error.3,v 1.4 2016/11/23 17:54:15 schwarze Exp $
+.\"	$OpenBSD: ERR_put_error.3,v 1.5 2017/02/20 23:21:19 beck Exp $
 .\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" This file was written by Ulf Moeller <ulf@openssl.org>.
@@ -48,12 +48,13 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 23 2016 $
+.Dd $Mdocdate: February 20 2017 $
 .Dt ERR_PUT_ERROR 3
 .Os
 .Sh NAME
 .Nm ERR_put_error ,
-.Nm ERR_add_error_data
+.Nm ERR_add_error_data ,
+.Nm ERR_add_error_vdata
 .Nd record an OpenSSL error
 .Sh SYNOPSIS
 .In openssl/err.h
@@ -97,6 +98,12 @@ string arguments with the error code added last.
 .Fn ERR_add_error_vdata
 is similar except the argument is a
 .Vt va_list .
+Use of
+.Fn ERR_add_error_data
+and
+.Fn ERR_add_error_vdata
+is deprecated inside of LibreSSL in favour of
+.Xr ERR_asprintf_error_data 3 .
 .Pp
 .Xr ERR_load_strings 3
 can be used to register error strings so that the application can
@@ -136,6 +143,7 @@ which must use the
 macro.
 .Sh SEE ALSO
 .Xr ERR 3 ,
+.Xr ERR_asprintf_error_data 3 ,
 .Xr ERR_load_strings 3
 .Sh HISTORY
 .Fn ERR_put_error
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 9a64837d311..75239dc3872 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.114 2017/01/31 05:40:26 schwarze Exp $
+# $OpenBSD: Makefile,v 1.115 2017/02/20 23:21:19 beck Exp $
 
 .include <bsd.own.mk>
 
@@ -92,6 +92,7 @@ MAN=	\
 	EC_POINT_new.3 \
 	ERR.3 \
 	ERR_GET_LIB.3 \
+	ERR_asprintf_error_data.3 \
 	ERR_clear_error.3 \
 	ERR_error_string.3 \
 	ERR_get_error.3 \