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

2. Preparation

To use `Libgcrypt', you have to perform some changes to your sources and the build system. The necessary changes are small and explained in the following sections. At the end of this chapter, it is described how the library is initialized, and how the requirements of the library are verified.


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

2.1 Header

All interfaces (data types and functions) of the library are defined in the header file `gcrypt.h'. You must include this in all source files using the library, either directly or through some other header file, like this:

 
#include <gcrypt.h>

The name space of `Libgcrypt' is gcry_* for function and type names and GCRY* for other symbols. In addition the same name prefixes with one prepended underscore are reserved for internal use and should never be used by an application. Furthermore `libgpg-error' defines functions prefixed with `gpg_' and preprocessor symbols prefixed with `GPG_'. Note that Libgcrypt uses libgpg-error, which uses gpg_err_* as name space for function and type names and GPG_ERR_* for other symbols, including all the error codes.


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

2.2 Building sources

If you want to compile a source file including the `gcrypt.h' header file, you must make sure that the compiler can find it in the directory hierarchy. This is accomplished by adding the path to the directory in which the header file is located to the compilers include file search path (via the `-I' option).

However, the path to the include file is determined at the time the source is configured. To solve this problem, `Libgcrypt' ships with a small helper program libgcrypt-config that knows the path to the include file and other configuration options. The options that need to be added to the compiler invocation at compile time are output by the `--cflags' option to libgcrypt-config. The following example shows how it can be used at the command line:

 
gcc -c foo.c `libgcrypt-config --cflags`

Adding the output of `libgcrypt-config --cflags' to the compilers command line will ensure that the compiler can find the `Libgcrypt' header file.

A similar problem occurs when linking the program with the library. Again, the compiler has to find the library files. For this to work, the path to the library files has to be added to the library search path (via the `-L' option). For this, the option `--libs' to libgcrypt-config can be used. For convenience, this option also outputs all other options that are required to link the program with the `Libgcrypt' libraries (in particular, the `-lgcrypt' option). The example shows how to link `foo.o' with the `Libgcrypt' library to a program foo.

 
gcc -o foo foo.o `libgcrypt-config --libs`

Of course you can also combine both examples to a single command by specifying both options to libgcrypt-config:

 
gcc -o foo foo.c `libgcrypt-config --cflags --libs`

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

2.3 Building sources using Automake

It is much easier if you use GNU Automake instead of writing your own Makefiles. If you do that you do not have to worry about finding and invoking the libgcrypt-config script at all. Libgcrypt provides an extension to Automake that does all the work for you.

Macro: AM_PATH_LIBGCRYPT ([minimum-version], [action-if-found], [action-if-not-found])

Check whether Libgcrypt (at least version minimum-version, if given) exists on the host system. If it is found, execute action-if-found, otherwise do action-if-not-found, if given.

Additionally, the function defines LIBGCRYPT_CFLAGS to the flags needed for compilation of the program to find the `gcrypt.h' header file, and LIBGCRYPT_LIBS to the linker flags needed to link the program to the Libgcrypt library.

You can use the defined Autoconf variables like this in your `Makefile.am':

 
AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS)
LDADD = $(LIBGCRYPT_LIBS)

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

2.4 Initializing the library

It is often desirable to check that the version of `Libgcrypt' used is indeed one which fits all requirements. Even with binary compatibility new features may have been introduced but due to problem with the dynamic linker an old version is actually used. So you may want to check that the version is okay right after program startup.

Function: const char *gcry_check_version (const char *req_version)

The function gcry_check_version has three purposes. It can be used to retrieve the version number of the library. In addition it can verify that the version number is higher than a certain required version number.

In either case, the function initializes some sub-systems, and for this reason alone it must be invoked early in your program, before you make use of the other functions of Libgcrypt.


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

2.5 Multi Threading

As mentioned earlier, the `Libgcrypt' library is thread-safe if you adhere to the following requirements:

Libgcrypt contains convenient macros, which define the necessary thread callbacks for PThread and for GNU Pth:

GCRY_THREAD_OPTION_PTH_IMPL

This macro defines the following (static) symbols: gcry_pth_init, gcry_pth_mutex_init, gcry_pth_mutex_destroy, gcry_pth_mutex_lock, gcry_pth_mutex_unlock, gcry_pth_read, gcry_pth_write, gcry_pth_select, gcry_pth_waitpid, gcry_pth_accept, gcry_pth_connect, gcry_threads_pth.

After including this macro, gcry_control() shall be used with a command of GCRYCTL_SET_THREAD_CBS in order to register the thread callback structure named "gcry_threads_pth".

GCRY_THREAD_OPTION_PTHREAD_IMPL

This macro defines the following (static) symbols: gcry_pthread_mutex_init, gcry_pthread_mutex_destroy, gcry_mutex_lock, gcry_mutex_unlock, gcry_threads_pthread.

After including this macro, gcry_control() shall be used with a command of GCRYCTL_SET_THREAD_CBS in order to register the thread callback structure named "gcry_threads_pthread".

Note that these macros need to be terminated with a semicolon. Keep in mind that these are convenient macros for C programmers; C++ programmers might have to wrap these macros in an "extern C" body.


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

This document was generated by root on October, 22 2007 using texi2html 1.76.