lib/libcrypto/man/ERR.3

   1 .\"     $OpenBSD: ERR.3,v 1.5 2016/11/23 17:54:15 schwarze Exp $
   2 .\"     OpenSSL 186bb907 Apr 13 11:05:13 2015 -0700
   3 .\"
   4 .\" This file was written by Ulf Moeller <ulf@openssl.org> and
   5 .\" Dr. Stephen Henson <steve@openssl.org>.
   6 .\" Copyright (c) 2000, 2015 The OpenSSL Project.  All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\"
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in
  17 .\"    the documentation and/or other materials provided with the
  18 .\"    distribution.
  19 .\"
  20 .\" 3. All advertising materials mentioning features or use of this
  21 .\"    software must display the following acknowledgment:
  22 .\"    "This product includes software developed by the OpenSSL Project
  23 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  24 .\"
  25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  26 .\"    endorse or promote products derived from this software without
  27 .\"    prior written permission. For written permission, please contact
  28 .\"    openssl-core@openssl.org.
  29 .\"
  30 .\" 5. Products derived from this software may not be called "OpenSSL"
  31 .\"    nor may "OpenSSL" appear in their names without prior written
  32 .\"    permission of the OpenSSL Project.
  33 .\"
  34 .\" 6. Redistributions of any form whatsoever must retain the following
  35 .\"    acknowledgment:
  36 .\"    "This product includes software developed by the OpenSSL Project
  37 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  38 .\"
  39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  42 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  51 .\"
  52 .Dd $Mdocdate: November 23 2016 $
  53 .Dt ERR 3
  54 .Os
  55 .Sh NAME
  56 .Nm ERR
  57 .Nd OpenSSL error codes
  58 .Sh SYNOPSIS
  59 .In openssl/err.h
  60 .Sh DESCRIPTION
  61 When a call to the OpenSSL library fails, this is usually signaled by
  62 the return value, and an error code is stored in an error queue
  63 associated with the current thread.
  64 The
  65 .Nm
  66 library provides functions to obtain these error codes and textual error
  67 messages.
  68 The
  69 .Xr ERR_get_error 3
  70 manpage describes how to access error codes.
  71 .Pp
  72 Error codes contain information about where the error occurred, and what
  73 went wrong.
  74 .Xr ERR_GET_LIB 3
  75 describes how to extract this information.
  76 A method to obtain human-readable error messages is described in
  77 .Xr ERR_error_string 3 .
  78 .Pp
  79 .Xr ERR_clear_error 3
  80 can be used to clear the error queue.
  81 .Pp
  82 Note that
  83 .Xr ERR_remove_state 3
  84 should be used to avoid memory leaks when threads are terminated.
  85 .Sh ADDING NEW ERROR CODES TO OPENSSL
  86 See
  87 .Xr ERR_put_error 3
  88 if you want to record error codes in the OpenSSL error system from
  89 within your application.
  90 .Pp
  91 The remainder of this section is of interest only if you want to add new
  92 error codes to OpenSSL or add error codes from external libraries.
  93 .Pp
  94 When you are using new function or reason codes, run
  95 .Sy make errors .
  96 The necessary
  97 .Sy #define Ns s
  98 will then automatically be added to the sub-library's header file.
  99 .Ss Adding new libraries
 100 When adding a new sub-library to OpenSSL, assign it a library number
 101 .Dv ERR_LIB_XXX ,
 102 define a macro
 103 .Fn XXXerr
 104 (both in
 105 .In openssl/err.h ) ,
 106 add its name to
 107 .Va ERR_str_libraries[]
 108 (in
 109 .Pa /usr/src/lib/libcrypto/err/err.c ) ,
 110 and add
 111 .Fn ERR_load_XXX_strings
 112 to the
 113 .Fn ERR_load_crypto_strings
 114 function (in
 115 .Sy /usr/src/lib/libcrypto/err/err_all.c ) .
 116 Finally, add an entry
 117 .Pp
 118 .Dl L XXX xxx.h xxx_err.c
 119 .Pp
 120 to
 121 .Sy /usr/src/lib/libcrypto/err/openssl.ec ,
 122 and add
 123 .Pa xxx_err.c
 124 to the
 125 .Pa Makefile .
 126 Running
 127 .Sy make errors
 128 will then generate a file
 129 .Pa xxx_err.c ,
 130 and add all error codes used in the library to
 131 .Pa xxx.h .
 132 .Pp
 133 Additionally the library include file must have a certain form.
 134 Typically it will initially look like this:
 135 .Bd -literal -offset indent
 136 #ifndef HEADER_XXX_H
 137 #define HEADER_XXX_H
 138
 139 #ifdef __cplusplus
 140 extern "C" {
 141 #endif
 142
 143 /* Include files */
 144
 145 #include <openssl/bio.h>
 146 #include <openssl/x509.h>
 147
 148 /* Macros, structures and function prototypes */
 149
 150 /* BEGIN ERROR CODES */
 151 .Ed
 152 .Pp
 153 The
 154 .Sy BEGIN ERROR CODES
 155 sequence is used by the error code generation script as the point to
 156 place new error codes.
 157 Any text after this point will be overwritten when
 158 .Sy make errors
 159 is run.
 160 The closing #endif etc. will be automatically added by the script.
 161 .Pp
 162 The generated C error code file
 163 .Pa xxx_err.c
 164 will load the header files
 165 .In stdio.h ,
 166 .In openssl/err.h
 167 and
 168 .In openssl/xxx.h
 169 so the header file must load any additional header files containing any
 170 definitions it uses.
 171 .Sh USING ERROR CODES IN EXTERNAL LIBRARIES
 172 It is also possible to use OpenSSL's error code scheme in external
 173 libraries.
 174 The library needs to load its own codes and call the OpenSSL error code
 175 insertion script
 176 .Pa mkerr.pl
 177 explicitly to add codes to the header file and generate the C error code
 178 file.
 179 This will normally be done if the external library needs to generate new
 180 ASN.1 structures but it can also be used to add more general purpose
 181 error code handling.
 182 .Sh INTERNALS
 183 The error queues are stored in a hash table with one
 184 .Vt ERR_STATE
 185 entry for each PID.
 186 .Fn ERR_get_state
 187 returns the current thread's
 188 .Vt ERR_STATE .
 189 An
 190 .Vt ERR_STATE
 191 can hold up to
 192 .Dv ERR_NUM_ERRORS
 193 error codes.
 194 When more error codes are added, the old ones are overwritten, on the
 195 assumption that the most recent errors are most important.
 196 .Pp
 197 Error strings are also stored in a hash table.
 198 The hash tables can be obtained by calling
 199 .Fn ERR_get_err_state_table
 200 and
 201 .Fn ERR_get_string_table .
 202 .Sh SEE ALSO
 203 .Xr CRYPTO_set_locking_callback 3 ,
 204 .Xr ERR_clear_error 3 ,
 205 .Xr ERR_error_string 3 ,
 206 .Xr ERR_get_error 3 ,
 207 .Xr ERR_GET_LIB 3 ,
 208 .Xr ERR_load_crypto_strings 3 ,
 209 .Xr ERR_load_strings 3 ,
 210 .Xr ERR_print_errors 3 ,
 211 .Xr ERR_put_error 3 ,
 212 .Xr ERR_remove_state 3 ,
 213 .Xr ERR_set_mark 3 ,
 214 .Xr SSL_get_error 3