From e8e5f59d71b35259c933157f7919776b1de45d0f Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 23 Nov 2016 17:54:15 +0000 Subject: Add Copyright and license. Like OpenSSL, move some text from ERR(3) to the fitting page ERR_put_error(3). Merge documentation of ERR_add_error_vdata(3) from OpenSSL. Drop useless statement about void functions returning no values. --- src/lib/libcrypto/man/ERR.3 | 88 ++++++++++++++++++------------- src/lib/libcrypto/man/ERR_put_error.3 | 98 ++++++++++++++++++++++++++++++++--- 2 files changed, 143 insertions(+), 43 deletions(-) diff --git a/src/lib/libcrypto/man/ERR.3 b/src/lib/libcrypto/man/ERR.3 index 6818a1cf46..973ba2713a 100644 --- a/src/lib/libcrypto/man/ERR.3 +++ b/src/lib/libcrypto/man/ERR.3 @@ -1,6 +1,55 @@ -.\" $OpenBSD: ERR.3,v 1.4 2016/11/17 21:06:16 jmc Exp $ +.\" $OpenBSD: ERR.3,v 1.5 2016/11/23 17:54:15 schwarze Exp $ +.\" OpenSSL 186bb907 Apr 13 11:05:13 2015 -0700 .\" -.Dd $Mdocdate: November 17 2016 $ +.\" This file was written by Ulf Moeller and +.\" Dr. Stephen Henson . +.\" Copyright (c) 2000, 2015 The OpenSSL Project. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" 3. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" 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 $ .Dt ERR 3 .Os .Sh NAME @@ -9,7 +58,7 @@ .Sh SYNOPSIS .In openssl/err.h .Sh DESCRIPTION -When a call to the OpenSSL library fails, this is usually signalled by +When a call to the OpenSSL library fails, this is usually signaled by the return value, and an error code is stored in an error queue associated with the current thread. The @@ -41,45 +90,12 @@ within your application. .Pp The remainder of this section is of interest only if you want to add new error codes to OpenSSL or add error codes from external libraries. -.Ss Reporting errors -Each sub-library has a specific macro -.Fn XXXerr f r -that is used to report errors. -Its first argument is a function code -.Dv XXX_F_* ; -the second argument is a reason code -.Dv XXX_R_* . -Function codes are derived from the function names -whereas reason codes consist of textual error descriptions. -For example, the function -.Fn ssl23_read -reports a "handshake failure" as follows: -.Pp -.Dl SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE); -.Pp -Function and reason codes should consist of upper case characters, -numbers and underscores only. -The error file generation script translates function codes into function -names by looking in the header files for an appropriate function name. -If none is found it just uses the capitalized form such as "SSL23_READ" -in the above example. -.Pp -The trailing section of a reason code (after the "_R_") is translated -into lower case and underscores changed to spaces. .Pp When you are using new function or reason codes, run .Sy make errors . The necessary .Sy #define Ns s will then automatically be added to the sub-library's header file. -.Pp -Although a library will normally report errors using its own specific -.Fn XXXerr -macro, another library's macro can be used. -This is normally only done when a library wants to include ASN.1 code -which must use the -.Fn ASN1err -macro. .Ss Adding new libraries When adding a new sub-library to OpenSSL, assign it a library number .Dv ERR_LIB_XXX , diff --git a/src/lib/libcrypto/man/ERR_put_error.3 b/src/lib/libcrypto/man/ERR_put_error.3 index 496d975165..2b41bedea3 100644 --- a/src/lib/libcrypto/man/ERR_put_error.3 +++ b/src/lib/libcrypto/man/ERR_put_error.3 @@ -1,6 +1,54 @@ -.\" $OpenBSD: ERR_put_error.3,v 1.3 2016/11/17 21:06:16 jmc Exp $ +.\" $OpenBSD: ERR_put_error.3,v 1.4 2016/11/23 17:54:15 schwarze Exp $ +.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" -.Dd $Mdocdate: November 17 2016 $ +.\" This file was written by Ulf Moeller . +.\" Copyright (c) 2000, 2016 The OpenSSL Project. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" 3. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" 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 $ .Dt ERR_PUT_ERROR 3 .Os .Sh NAME @@ -22,6 +70,11 @@ .Fa "int num" .Fa ... .Fc +.Ft void +.Fo ERR_add_error_vdata +.Fa "int num" +.Fa "va_list arg" +.Fc .Sh DESCRIPTION .Fn ERR_put_error adds an error code to the thread's error queue. @@ -41,15 +94,46 @@ This function is usually called by a macro. associates the concatenation of its .Fa num string arguments with the error code added last. +.Fn ERR_add_error_vdata +is similar except the argument is a +.Vt va_list . .Pp .Xr ERR_load_strings 3 can be used to register error strings so that the application can generate human-readable error messages for the error code. -.Sh RETURN VALUES -.Fn ERR_put_error -and -.Fn ERR_add_error_data -return no values. +.Pp +Each sub-library has a specific macro +.Fn XXXerr f r +that is used to report errors. +Its first argument is a function code +.Dv XXX_F_* ; +the second argument is a reason code +.Dv XXX_R_* . +Function codes are derived from the function names +whereas reason codes consist of textual error descriptions. +For example, the function +.Fn ssl23_read +reports a "handshake failure" as follows: +.Pp +.Dl SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE); +.Pp +Function and reason codes should consist of upper case characters, +numbers and underscores only. +The error file generation script translates function codes into function +names by looking in the header files for an appropriate function name. +If none is found it just uses the capitalized form such as "SSL23_READ" +in the above example. +.Pp +The trailing section of a reason code (after the "_R_") is translated +into lower case and underscores changed to spaces. +.Pp +Although a library will normally report errors using its own specific +.Fn XXXerr +macro, another library's macro can be used. +This is normally only done when a library wants to include ASN.1 code +which must use the +.Fn ASN1err +macro. .Sh SEE ALSO .Xr ERR 3 , .Xr ERR_load_strings 3 -- cgit v1.2.3-55-g6feb