	RSA BSAFE SSL-C	Security protocol components for C
		Search

Error Reporting Functions

This section includes functions that can be used to obtain information from the library about errors that occurred during operations.

Functions
void	ERR_load_strings (int lib, ERR_STRING_DATA *str)
	Loads the given packed error code and corresponding string into the hash table. More...
void	ERR_free_strings (void)
	Frees all the loaded error strings. More...
void	ERR_remove_state (unsigned long pid)
	Frees the error stack associated with a specific thread/process identifier. More...
void	ERR_put_error (int lib, int func, int reason, char *file, int line)
	Places an error from the library lib for the function func with the reason reason in the global error stack. More...
void	ERR_clear_error ()
	Clears the error buffer and discards all unread errors.
unsigned long	ERR_get_error (void)
	Retrieves the latest error from the error stack. More...
unsigned long	ERR_peek_error (void)
	Retrieves the latest error from the error stack. More...
char*	ERR_error_string (unsigned long error_code, char *buf)
	Retrieves the file name and line number where the error occurred, and the data and flags of the error. More...
char*	ERR_lib_error_string (unsigned long error_code)
	Retrieves the library string associated with a particular error code. More...
char*	ERR_func_error_string (unsigned long error_code)
	Retrieves the function string associated with a particular error code. More...
char*	ERR_reason_error_string (unsigned long error_code)
	Retrieves the reason string associated with a particular error code. More...
void	ERR_print_errors_fp (FILE *fp)
	Prints the error stack to the file pointer fp. More...
void	ERR_print_errors (BIO *bio)
	Prints the error stack to the BIO bio. More...

Function Documentation

char* ERR_error_string ( unsigned long error_code,

char * ret

) ;

Retrieves the file name and line number where the error occurred, and the data and flags of the error.
Parameters:

error_code [In] A packed error code.

ret [Out] The buffer containing the error strings associated with the packed error code.

Returns:
The buffer containing the error strings associated with the packed error code.

Not suitable for multithreaded programs, because it uses a local buffer if ret == NULL.

void ERR_free_strings ( void ) ;

Frees all the loaded error strings. This is only applicable when error strings have been loaded via any of the error load strings functions.

char* ERR_func_error_string ( unsigned long error_code ) ;

Retrieves the function string associated with a particular error code.
Parameters:

error_code [In] A packed error code.

Returns:
The string identifying the function-specific part of the packed error code if available, otherwise NULL.

unsigned long ERR_get_error ( void ) ;

Retrieves the latest error from the error stack. This is a destructive operation since the error is removed from the stack at the same time. Other errors that may also exist in the stack are not affected.

Returns:
The latest error code from the stack if available.
Use ERR_error_string() to view the accompanying test.

Repeated calls to this function will return error codes until the stack is empty. When the stack is empty a value of 0 is returned.
Samples:
fips_client.c, and simple.c.

char* ERR_lib_error_string ( unsigned long error_code ) ;

Retrieves the library string associated with a particular error code.
Parameters:

error_code [In] A packed error code.

Returns:
The string identifying the library-specific part of the packed error code.

void ERR_load_strings ( int lib,

ERR_STRING_DATA * str

) ;

Loads the given packed error code and corresponding string into the hash table.
Parameters:

lib [in] The code to represent a library.

str [in] The ERR_STRING_DATA reference.

unsigned long ERR_peek_error ( void ) ;

Retrieves the latest error from the error stack. This is a non-destructive operation since the error remains on the stack. Other errors that may also exist in the stack are not affected.

Returns:
The latest error code from the stack, if available.
Use ERR_error_string() to view the accompanying test.
Samples:
fips_client.c, and simple.c.

void ERR_print_errors ( BIO * bio ) ;

Prints the error stack to the BIO bio.
Parameters:

bio [In] A BIO reference to be used as the output channel for the error information.

See also:
ERR_print_errors_fp().
Samples:
bio_client.c, bio_server.c, cache_server.c, fips_client.c, nbio_client.c, nbio_server.c, PKCS11Client.c, s_frombuf.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

void ERR_print_errors_fp ( FILE * fp ) ;

Prints the error stack to the file pointer fp.
Parameters:

fp [In] The FILE reference.

This function is not available under WIN16. Use ERR_print_errors() instead.
See also:
ERR_print_errors().
Samples:
simple.c.

void ERR_put_error ( int lib,

int func,

int reason,

char * file,

int line

) ;

Places an error from the library lib for the function func with the reason reason in the global error stack.
Parameters:

lib [In] The library where the error occurred.

func [In] The function where error occurred.

reason [In] The reason for the error.

file [In] The name of the source code file in which the error occurred.

line [In] The line number in the file where the error occurred.

The error stack stores a maximum of 16 errors. Once this limit is reached, the errors are cycled (that is, the earliest error is removed from the error stack and the latest error is appended to the top of the stack). Since the error stack is cyclical, it is important to check the error stack regularly to avoid an error being overwritten by subsequent errors. The error stack can be cleared at any time using ERR_clear_error().
See also:
ERR_clear_error() and ERR_get_error().

char* ERR_reason_error_string ( unsigned long error_code ) ;

Retrieves the reason string associated with a particular error code.
Parameters:

error_code [In] A packed error code.

Returns:
The string identifying the reason-specific part of the packet error code if available, otherwise NULL.

void ERR_remove_state ( unsigned long pid ) ;

Frees the error stack associated with a specific thread/process identifier.
Parameters:

pid [In] The process identifier of the error stack to free.

If the process identifier is 0, the error stack for the current process is removed. If a thread is terminated, the error stack for that thread should also be removed. Failure to do this will result in a memory leak.