     [file version.texi not included]

The Libgpg-error Library
************************

This manual is for Libgpg-error (version VERSION, UPDATED), which is a library for code used by all GnuPG related packages.

Copyright © 2014 g10 Code GmbH

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. The text of the license can be found in the section entitled ``GNU General Public License''.

Introduction
************

Libgpg-error is a library to provide error codes for GnuPG and relates software as well as some other general purpose functions.  It is planned to eventually rename this library to ``gpgrt'' (for GnuPG RunTime).

Getting Started
===============

This manual documents the Libgpg-error library application programming interface (API).  The goal is to that all functions and data types provided by the library are explained.  However, for now this is only a stub and not very useful.

Features
========

TBD

Overview
========

The Libgpg-error library is fully thread-safe, where it makes sense to be thread-safe.

TBD

Preparation
***********

To use Libgpg-error, 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.

Header
======

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

     #include <libgpg-error.h>

Note well that the header file is platform specific and may only be used on the platform for which it has been build.

The name space of Libgpg-error is gpg_* and gpgrt* for function and type names and GPG_* and GPGRT_* 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.

Certain parts of gpg-error.h may be included by defining these macros:

GPG_ERR_ENABLE_GETTEXT_MACROS
     Define to provide macros to map the internal gettext API to standard names.  This has only an effect on Windows platforms.

GPGRT_ENABLE_ES_MACROS
     Define to provide "es_" macros for the estream functions.

Building sources
================

If you want to compile a source file including the `gpg-error.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, Libgpg-error ships with a small helper program gpg-error-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 gpg-error-config.  The following example shows how it can be used at the command line:

     gcc -c foo.c $(gpg-error-config --cflags)

Adding the output of gpg-error-config --cflags to the compiler’s command line will ensure that the compiler can find the Libgpg-error 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 gpg-error-config can be used.  The example shows how to link foo.o with the Libgpg-error library to a program foo.

     gcc -o foo foo.o $(gpg-error-config --libs)

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

     gcc -o foo foo.c $(gpg-error-config --cflags --libs)

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 gpg-error-config script at all.  Libgpg-error provides an extension to Automake that does all the work for you.

 -- Macro: AM_PATH_GPG_ERROR ([minimum-version], [action-if-found], [action-if-not-found])
     Check whether Libgpg-error (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 GPG_ERROR_CFLAGS to the flags needed for compilation of the program to find the gpg-error.h header file, and GPG_ERROR_LIBS to the linker flags needed to link the program to the Libgpg-error library.  If the used helper script does not match the target type you are building for a warning is printed and the string libgpg-error is appended to the variable gpg_config_script_warn.

     This macro searches for gpg-error-config along the PATH.  If you are cross-compiling, it is useful to set the environment variable SYSROOT to the top directory of your target.  The macro will then first look for the helper program in the bin directory below that top directory.  An absolute directory name must be used for SYSROOT.  Finally, if the configure command line option --with-libgpg-error-prefix is used, only its value is used for the top directory below which the helper script is expected.

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

     AM_CPPFLAGS = $(GPG_ERROR_CFLAGS)
     LDADD = $(GPG_ERROR_LIBS)

Initializing the library
========================

Before the library can be used, it should initialize itself.  This is achieved by invoking the function gpgrt_check_version described below.

Also, it is often desirable to check that the version of Libgpg-error 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 may actually be used.  So you may want to check that the version is okay right after program startup.

 -- Function: const char * gpgrt_check_version (const char *REQ_VERSION)

     The function gpgrt_check_version initializes some subsystems used by Libgpg-error and must be invoked before any other function in the library. See Multi-Threading.

     Furthermore, this function returns the version number of the library. It can also verify that the version number is higher than a certain required version number REQ_VERSION, if this value is not a null pointer.

Multi-Threading
===============

TBD.

Generalities
************

TBD.  (Description of the error function may be taken from Libgcrypt.)

Tools
*****

Print required compiler flags
=============================

gpg-error-config is a tool that is used to configure to determine the compiler and linker flags that should be used to compile and link programs that use Libgpg-error. It is also used internally to the .m4 macros for GNU autoconf that are included with Libgpg-error.

gpg-error-config accepts the following options:

--mt
     Provide output appropriate for multithreaded programs.  --mt is only useful when combined with other options, and must be the first option if present.

--version
     Print the currently installed version of Libgpg-error on the standard output.

--libs
     Print the linker flags that are necessary to link a program using Libgpg-error.

--cflags
     Print the compiler flags that are necessary to compile a program using Libgpg-error.

--prefix=PREFIX
     If specified, use PREFIX instead of the installation prefix that Libgpg-error was built with when computing the output for the --cflags and --libs options.  This option is also used for the exec prefix if --exec-prefix was not specified. This option must be specified before any --libs or --cflags options.

--exec-prefix=PREFIX
     If specified, use PREFIX instead of the installation exec prefix that Libgpg-error was built with when computing the output for the --cflags and --libs options.  This option must be specified before any --libs or --cflags options.

     [file lgpl.texi not included]

     [file gpl.texi not included]