doc/error.doc

   1 The error routines.
   2
   3 The 'error' system I've implemented is intended to server 2 purpose, to
   4 record the reason why a command failed and to record where in the libraries
   5 the failure occurred.  It is more or less setup to record a 'trace' of which
   6 library components were being traversed when the error occurred.
   7
   8 When an error is recorded, it is done so a as single unsigned long which is
   9 composed of three parts.  The top byte is the 'library' number, the middle
  10 12 bytes is the function code, and the bottom 12 bits is the 'reason' code.
  11
  12 Each 'library', or should a say, 'section' of the SSLeay library has a
  13 different unique 'library' error number.  Each function in the library has
  14 a number that is unique for that library.  Each 'library' also has a number
  15 for each 'error reason' that is only unique for that 'library'.
  16
  17 Due to the way these error routines record a 'error trace', there is an
  18 array per thread that is used to store the error codes.
  19 The various functions in this library are used to access
  20 and manipulate this array.
  21
  22 void ERR_put_error(int lib, int func,int reason);
  23         This routine records an error in library 'lib', function 'func'
  24 and reason 'reason'.  As errors get 'put' into the buffer, they wrap
  25 around and overwrite old errors if too many are written.  It is assumed
  26 that the last errors are the most important.
  27
  28 unsigned long ERR_get_error(void );
  29         This function returns the last error added to the error buffer.
  30 In effect it is popping the value off the buffer so repeated calls will
  31 continue to return values until there are no more errors to return in which
  32 case 0 is returned.
  33
  34 unsigned long ERR_peek_error(void );
  35         This function returns the value of the last error added to the
  36 error buffer but does not 'pop' it from the buffer.
  37
  38 void ERR_clear_error(void );
  39         This function clears the error buffer, discarding all unread
  40 errors.
  41
  42 While the above described error system obviously produces lots of different
  43 error number, a method for 'reporting' these errors in a human readable
  44 form is required.  To achieve this, each library has the option of
  45 'registering' error strings.
  46
  47 typedef struct ERR_string_data_st
  48         {
  49         unsigned long error;
  50         char *string;
  51         } ERR_STRING_DATA;
  52
  53 The 'ERR_STRING_DATA' contains an error code and the corresponding text
  54 string.  To add new function error strings for a library, the
  55 ERR_STRING_DATA needs to be 'registered' with the library.
  56
  57 void ERR_load_strings(unsigned long lib,ERR_STRING_DATA *err);
  58         This function 'registers' the array of ERR_STRING_DATA pointed to by
  59 'err' as error text strings for the error library 'lib'.
  60
  61 void ERR_free_strings(void);
  62         This function free()s all the loaded error strings.
  63
  64 char *ERR_error_string(unsigned long error,char *buf);
  65         This function returns a text string that is a human readable
  66 version of the error represented by 'error'.  Buff should be at least 120
  67 bytes long and if it is NULL, the return value is a pointer to a static
  68 variable that will contain the error string, otherwise 'buf' is returned.
  69 If there is not a text string registered for a particular error, a text
  70 string containing the error number is returned instead.
  71
  72 void ERR_print_errors(BIO *bp);
  73 void ERR_print_errors_fp(FILE *fp);
  74         This function is a convenience routine that prints the error string
  75 for each error until all errors have been accounted for.
  76
  77 char *ERR_lib_error_string(unsigned long e);
  78 char *ERR_func_error_string(unsigned long e);
  79 char *ERR_reason_error_string(unsigned long e);
  80 The above three functions return the 3 different components strings for the
  81 error 'e'.  ERR_error_string() uses these functions.
  82
  83 void ERR_load_ERR_strings(void );
  84         This function 'registers' the error strings for the 'ERR' module.
  85
  86 void ERR_load_crypto_strings(void );
  87         This function 'register' the error strings for just about every
  88 library in the SSLeay package except for the SSL routines.  There is no
  89 need to ever register any error text strings and you will probably save in
  90 program size.  If on the other hand you do 'register' all errors, it is
  91 quite easy to determine why a particular routine failed.
  92
  93 As a final footnote as to why the error system is designed as it is.
  94 1) I did not want a single 'global' error code.
  95 2) I wanted to know which subroutine a failure occurred in.
  96 3) For Windows NT etc, it should be simple to replace the 'key' routines
  97    with code to pass error codes back to the application.
  98 4) I wanted the option of meaningful error text strings.
  99
 100 Late breaking news - the changes to support threads.
 101
 102 Each 'thread' has an 'ERR_STATE' state associated with it.
 103 ERR_STATE *ERR_get_state(void ) will return the 'state' for the calling
 104 thread/process.
 105
 106 ERR_remove_state(unsigned long pid); will 'free()' this state.  If pid == 0
 107 the current 'thread/process' will have it's error state removed.
 108 If you do not remove the error state of a thread, this could be considered a
 109 form of memory leak, so just after 'reaping' a thread that has died,
 110 call ERR_remove_state(pid).
 111
 112 Have a read of thread.doc for more details for what is required for
 113 multi-threading support.  All the other error routines will
 114 work correctly when using threads.
 115