Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ERR(3)			 BSD Library Functions Manual			ERR(3)

NAME
     ERR -- OpenSSL error codes

SYNOPSIS
     #include <openssl/err.h>

DESCRIPTION
     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 ERR library provides	functions to obtain
     these error codes and textual error messages.  The	ERR_get_error(3) man-
     page describes how	to access error	codes.

     Error codes contain information about where the error occurred, and what
     went wrong.  ERR_GET_LIB(3) describes how to extract this information.  A
     method to obtain human-readable error messages is described in
     ERR_error_string(3).

     ERR_clear_error(3)	can be used to clear the error queue.

     Note that ERR_remove_state(3) should be used to avoid memory leaks	when
     threads are terminated.

ADDING NEW ERROR CODES TO OPENSSL
     See ERR_put_error(3) if you want to record	error codes in the OpenSSL er-
     ror system	from within your application.

     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.

     When you are using	new function or	reason codes, run make errors.	The
     necessary #defines	will then automatically	be added to the	sub-library's
     header file.

   Adding new libraries
     When adding a new sub-library to OpenSSL, assign it a library number
     ERR_LIB_XXX, define a macro XXXerr() (both	in <openssl/err.h>), add its
     name to ERR_str_libraries[] (in /usr/src/lib/libcrypto/err/err.c),	and
     add ERR_load_XXX_strings()	to the ERR_load_crypto_strings() function (in
     /usr/src/lib/libcrypto/err/err_all.c).  Finally, add an entry

	   L XXX xxx.h xxx_err.c

     to	/usr/src/lib/libcrypto/err/openssl.ec, and add xxx_err.c to the
     Makefile.	Running	make errors will then generate a file xxx_err.c, and
     add all error codes used in the library to	xxx.h.

     Additionally the library include file must	have a certain form.  Typi-
     cally it will initially look like this:

	   #ifndef HEADER_XXX_H
	   #define HEADER_XXX_H

	   #ifdef __cplusplus
	   extern "C" {
	   #endif

	   /* Include files */

	   #include <openssl/bio.h>
	   #include <openssl/x509.h>

	   /* Macros, structures and function prototypes */

	   /* BEGIN ERROR CODES	*/

     The BEGIN ERROR CODES sequence is used by the error code generation
     script as the point to place new error codes.  Any	text after this	point
     will be overwritten when make errors is run.  The closing #endif etc.
     will be automatically added by the	script.

     The generated C error code	file xxx_err.c will load the header files
     <stdio.h>,	<openssl/err.h>	and <openssl/xxx.h> so the header file must
     load any additional header	files containing any definitions it uses.

USING ERROR CODES IN EXTERNAL LIBRARIES
     It	is also	possible to use	OpenSSL's error	code scheme in external	li-
     braries.  The library needs to load its own codes and call	the OpenSSL
     error code	insertion script mkerr.pl explicitly to	add codes to the
     header file and generate the C error code file.  This will	normally be
     done if the external library needs	to generate new	ASN.1 structures but
     it	can also be used to add	more general purpose error code	handling.

INTERNALS
     The error queues are stored in a hash table with one ERR_STATE entry for
     each PID.	ERR_get_state()	returns	the current thread's ERR_STATE.	 An
     ERR_STATE can hold	up to ERR_NUM_ERRORS error codes.  When	more error
     codes are added, the old ones are overwritten, on the assumption that the
     most recent errors	are most important.

     Error strings are also stored in a	hash table.  The hash tables can be
     obtained by calling ERR_get_err_state_table() and ERR_get_string_table().

SEE ALSO
     CRYPTO_set_locking_callback(3), ERR_clear_error(3), ERR_error_string(3),
     ERR_get_error(3), ERR_GET_LIB(3), ERR_load_crypto_strings(3),
     ERR_load_strings(3), ERR_print_errors(3), ERR_put_error(3),
     ERR_remove_state(3), ERR_set_mark(3), SSL_get_error(3)

BSD			       November	23, 2016			   BSD

NAME | SYNOPSIS | DESCRIPTION | ADDING NEW ERROR CODES TO OPENSSL | USING ERROR CODES IN EXTERNAL LIBRARIES | INTERNALS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ERR&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help