[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Handler Functions

Libgcrypt makes it possible to install so called `handler functions', which get called by Libgcrypt in case of certain events.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 Progress handler

It is often useful to retrieve some feedback while long running operations are performed.

Data type: gcry_handler_progress_t

Progress handler functions have to be of the type gcry_handler_progress_t, which is defined as:

void (*gcry_handler_progress_t) (void *, const char *, int, int, int)

The following function may be used to register a handler function for this purpose.

Function: void gcry_set_progress_handler (gcry_handler_progress_t cb, void *cb_data)

This function installs cb as the `Progress handler' function. It may be used only during initialization. cb must be defined as follows:

my_progress_handler (void *cb_data, const char *what,
                     int printchar, int current, int total)
  /* Do something.  */

A description of the arguments of the progress handler function follows.


The argument provided in the call to gcry_set_progress_handler.


A string identifying the type of the progress output. The following values for what are defined:


Not enough entropy is available. total holds the number of required bytes.


Values for printchar:


Prime generated.


Need to refresh the pool of prime numbers.

<, >

Number of bits adjusted.


Searching for a generator.


Fermat test on 10 candidates failed.


Restart with a new random value.


Rabin Miller test passed.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 Allocation handler

It is possible to make Libgcrypt use special memory allocation functions instead of the built-in ones.

Memory allocation functions are of the following types:

Data type: gcry_handler_alloc_t

This type is defined as: void *(*gcry_handler_alloc_t) (size_t n).

Data type: gcry_handler_secure_check_t

This type is defined as: int *(*gcry_handler_secure_check_t) (const void *).

Data type: gcry_handler_realloc_t

This type is defined as: void *(*gcry_handler_realloc_t) (void *p, size_t n).

Data type: gcry_handler_free_t

This type is defined as: void *(*gcry_handler_free_t) (void *).

Special memory allocation functions can be installed with the following function:

Function: void gcry_set_allocation_handler (gcry_handler_alloc_t func_alloc, gcry_handler_alloc_t func_alloc_secure, gcry_handler_secure_check_t func_secure_check, gcry_handler_realloc_t func_realloc, gcry_handler_free_t func_free)

Install the provided functions and use them instead of the built-in functions for doing memory allocation. Using this function is in general not recommended because the standard Libgcrypt allocation functions are guaranteed to zeroize memory if needed.

This function may be used only during initialization and may not be used in fips mode.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 Error handler

The following functions may be used to register handler functions that are called by Libgcrypt in case certain error conditions occur. They may and should be registered prior to calling gcry_check_version.

Data type: gcry_handler_no_mem_t

This type is defined as: int (*gcry_handler_no_mem_t) (void *, size_t, unsigned int)

Function: void gcry_set_outofcore_handler (gcry_handler_no_mem_t func_no_mem, void *cb_data)

This function registers func_no_mem as `out-of-core handler', which means that it will be called in the case of not having enough memory available. The handler is called with 3 arguments: The first one is the pointer cb_data as set with this function, the second is the requested memory size and the last being a flag. If bit 0 of the flag is set, secure memory has been requested. The handler should either return true to indicate that Libgcrypt should try again allocating memory or return false to let Libgcrypt use its default fatal error handler.

Data type: gcry_handler_error_t

This type is defined as: void (*gcry_handler_error_t) (void *, int, const char *)

Function: void gcry_set_fatalerror_handler (gcry_handler_error_t func_error, void *cb_data)

This function registers func_error as `error handler', which means that it will be called in error conditions.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4 Logging handler

Data type: gcry_handler_log_t

This type is defined as: void (*gcry_handler_log_t) (void *, int, const char *, va_list)

Function: void gcry_set_log_handler (gcry_handler_log_t func_log, void *cb_data)

This function registers func_log as `logging handler', which means that it will be called in case Libgcrypt wants to log a message. This function may and should be used prior to calling gcry_check_version.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on January, 20 2010 using texi2html 1.76.