[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
2.1 Header | What header file you need to include. | |
2.2 Building sources | How to build sources using the library. | |
2.3 Building sources using Automake | How to build sources with the help auf Automake. | |
2.4 Initializing the library | How to initialize the library. | |
2.5 Multi Threading | How Libgcrypt can be used in a MT environment. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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.
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] | [ ? ] |
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.
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] | [ ? ] |
As mentioned earlier, the `Libgcrypt' library is thread-safe if you adhere to the following requirements:
GCRYCTL_SET_THREAD_CBS
command
before any other function in the library.
This is easy enough if you are indeed writing an application using libgcrypt. It is rather problematic if you are writing a library instead. Here are some tips what to do if you are writing a library:
If your library requires a certain thread package, just initialize gcrypt to use this thread package. If your library supports multiple thread packages, but needs to be configured, you will have to implement a way to determine which thread package the application wants to use with your library anyway. Then configure gcrypt to use this thread package.
If your library is fully reentrant without any special support by a thread package, then you are lucky indeed. Unfortunately, this does not relieve you from doing either of the two above, or use a third option. The third option is to let the application initialize gcrypt for you. Then you are not using gcrypt transparently, though.
As if this was not difficult enough, a conflict may arise if two libraries try to initialize gcrypt independently of each others, and both such libraries are then linked into the same application. To make it a bit simpler for you, this will probably work, but only if both libraries have the same requirement for the thread package. This is currently only supported for the non-threaded case, GNU Pth and pthread. Support for more thread packages is easy to add, so contact is if you require it.
gcry_check_version
must be called before any other
function in the library, except the GCRYCTL_SET_THREAD_CBS
command, because it initializes the thread support subsystem in
Libgcrypt. To achieve this in multi-threaded programs, you
must synchronize the memory with respect to other threads that also
want to use Libgcrypt. For this, it is sufficient to call
gcry_check_version
before creating the other threads using
Libgcrypt(1).
gpg_strerror
, gcry_strerror
is not
thread safe. You have to use gpg_strerror_r
instead.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |