lib/libcrypto/man/ERR_put_error.3

   1 .\"     $OpenBSD: ERR_put_error.3,v 1.5 2017/02/20 23:21:19 beck Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Ulf Moeller <ulf@openssl.org>.
   5 .\" Copyright (c) 2000, 2016 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: February 20 2017 $
  52 .Dt ERR_PUT_ERROR 3
  53 .Os
  54 .Sh NAME
  55 .Nm ERR_put_error ,
  56 .Nm ERR_add_error_data ,
  57 .Nm ERR_add_error_vdata
  58 .Nd record an OpenSSL error
  59 .Sh SYNOPSIS
  60 .In openssl/err.h
  61 .Ft void
  62 .Fo ERR_put_error
  63 .Fa "int lib"
  64 .Fa "int func"
  65 .Fa "int reason"
  66 .Fa "const char *file"
  67 .Fa "int line"
  68 .Fc
  69 .Ft void
  70 .Fo ERR_add_error_data
  71 .Fa "int num"
  72 .Fa ...
  73 .Fc
  74 .Ft void
  75 .Fo ERR_add_error_vdata
  76 .Fa "int num"
  77 .Fa "va_list arg"
  78 .Fc
  79 .Sh DESCRIPTION
  80 .Fn ERR_put_error
  81 adds an error code to the thread's error queue.
  82 It signals that the error of reason code
  83 .Fa reason
  84 occurred in function
  85 .Fa func
  86 of library
  87 .Fa lib ,
  88 in line number
  89 .Fa line
  90 of
  91 .Fa file .
  92 This function is usually called by a macro.
  93 .Pp
  94 .Fn ERR_add_error_data
  95 associates the concatenation of its
  96 .Fa num
  97 string arguments with the error code added last.
  98 .Fn ERR_add_error_vdata
  99 is similar except the argument is a
 100 .Vt va_list .
 101 Use of
 102 .Fn ERR_add_error_data
 103 and
 104 .Fn ERR_add_error_vdata
 105 is deprecated inside of LibreSSL in favour of
 106 .Xr ERR_asprintf_error_data 3 .
 107 .Pp
 108 .Xr ERR_load_strings 3
 109 can be used to register error strings so that the application can
 110 generate human-readable error messages for the error code.
 111 .Pp
 112 Each sub-library has a specific macro
 113 .Fn XXXerr f r
 114 that is used to report errors.
 115 Its first argument is a function code
 116 .Dv XXX_F_* ;
 117 the second argument is a reason code
 118 .Dv XXX_R_* .
 119 Function codes are derived from the function names
 120 whereas reason codes consist of textual error descriptions.
 121 For example, the function
 122 .Fn ssl23_read
 123 reports a "handshake failure" as follows:
 124 .Pp
 125 .Dl SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE);
 126 .Pp
 127 Function and reason codes should consist of upper case characters,
 128 numbers and underscores only.
 129 The error file generation script translates function codes into function
 130 names by looking in the header files for an appropriate function name.
 131 If none is found it just uses the capitalized form such as "SSL23_READ"
 132 in the above example.
 133 .Pp
 134 The trailing section of a reason code (after the "_R_") is translated
 135 into lower case and underscores changed to spaces.
 136 .Pp
 137 Although a library will normally report errors using its own specific
 138 .Fn XXXerr
 139 macro, another library's macro can be used.
 140 This is normally only done when a library wants to include ASN.1 code
 141 which must use the
 142 .Fn ASN1err
 143 macro.
 144 .Sh SEE ALSO
 145 .Xr ERR 3 ,
 146 .Xr ERR_asprintf_error_data 3 ,
 147 .Xr ERR_load_strings 3
 148 .Sh HISTORY
 149 .Fn ERR_put_error
 150 is available in all versions of SSLeay and OpenSSL.
 151 .Fn ERR_add_error_data
 152 was added in SSLeay 0.9.0.