|
Packit |
fc043f |
What is Libgpg-error
|
|
Packit |
fc043f |
====================
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
Libgpg-error is a library that defines common error values for all
|
|
Packit |
fc043f |
GnuPG components. Among these are GPG, GPGSM, GPGME, GPG-Agent,
|
|
Packit |
fc043f |
libgcrypt, Libksba, DirMngr, Pinentry, SmartCard Daemon and more.
|
|
Packit |
fc043f |
Meanwhile Libgcrypt also sports functions commonly used by all GnuPG
|
|
Packit |
fc043f |
components and which are believed to be generally useful. The main
|
|
Packit |
fc043f |
components are
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
- Structured error codes and utility functions.
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
- Replacement functions for stdio stream (estream) to provide a
|
|
Packit |
fc043f |
reliable set of printf features on all platforms. For convenience
|
|
Packit |
fc043f |
macros are provided to make migration from stdio to estream easier
|
|
Packit |
fc043f |
(ie. the prefix "es_")
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
- Generic Mutex implementation for all platforms using an ABI
|
|
Packit |
fc043f |
independent of the underlying implementation.
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
- A lean gettext and iconv implementation for Windows.
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
- Log functions
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
- Option parser
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
- BAse-64 encoder and decoder.
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
More components will be added over time. Most functions are prefixed
|
|
Packit |
fc043f |
with "gpgrt" (GnuPG Run Time) instead of "gpg_err" to indicate the
|
|
Packit |
fc043f |
long term plan to rename this library to gpgrt.
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
Libgpg-error is free software; you can redistribute it and/or modify
|
|
Packit |
fc043f |
it under the terms of the GNU Lesser General Public License as
|
|
Packit |
fc043f |
published by the Free Software Foundation; either version 2.1 of the
|
|
Packit |
fc043f |
License, or (at your option) any later version. See the file
|
|
Packit |
fc043f |
COPYING.LIB for copyright and warranty information. See the file
|
|
Packit |
fc043f |
AUTHORS for a list of authors and important mail addresses.
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
However, some files (for example src/mkerrnos.awk) used in the build
|
|
Packit |
fc043f |
process of the library and the manual are covered by a different
|
|
Packit |
fc043f |
license. Please see the header of these files and the file COPYING
|
|
Packit |
fc043f |
for copyright and warranty information on these files. A special
|
|
Packit |
fc043f |
exception in the copyright license of these files makes sure that the
|
|
Packit |
fc043f |
output in the build process, which is used in libgpg-error, is not
|
|
Packit |
fc043f |
affected by the GPL.
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
Installation
|
|
Packit |
fc043f |
============
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
Please read the file INSTALL!
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
Here is a quick summary:
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
1) Check that you have unmodified sources. You can find instructions
|
|
Packit |
fc043f |
how to verify the sources below. Don't skip this - it is an
|
|
Packit |
fc043f |
important step!
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
2) Unpack the archive. With GNU tar you can do it this way:
|
|
Packit |
fc043f |
"tar xjvf libgpg-error-x.y.tar.bz2"
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
3) "cd libgpg-error-x.y"
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
4) "./configure"
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
5) "make"
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
6) "make install"
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
How to Verify the Source
|
|
Packit |
fc043f |
========================
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
In order to check that the version of libgpg-error which you are going
|
|
Packit |
fc043f |
to install is an original and unmodified copy of the original, you can
|
|
Packit |
fc043f |
do it in one of the following ways:
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
a) If you already have a trusted version of GnuPG installed, you can
|
|
Packit |
fc043f |
simply check the supplied signature:
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
$ gpg --verify libgpg-error-x.y.tar.bz2.sig libgpg-error-x.y.tar.bz2
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
This checks that the detached signature libgpg-error-x.y.tar.bz2.sig
|
|
Packit |
fc043f |
is indeed a signature of libgpg-error-x.y.tar.bz2. Make sure that
|
|
Packit |
fc043f |
the signature has been created by a trusted keys.
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
Please note that you have to use an old version of GnuPG to do all
|
|
Packit |
fc043f |
this stuff. *Never* use the version which was built using the
|
|
Packit |
fc043f |
library you are trying to verify!
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
b) If you don't have any a trusted version of GnuPG, you can attempt
|
|
Packit |
fc043f |
to verify the SHA1 checksum, using a trusted version of the sha1sum
|
|
Packit |
fc043f |
program:
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
$ sha1sum libgpg-error-x.y.tar.bz2
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
This should yield an output _similar_ to this:
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
610064e5b77700f5771c8fde2691c4365e1ca100 libgpg-error-x.y.tar.bz2
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
Now check that this checksum is _exactly_ the same as the one
|
|
Packit |
fc043f |
published via the announcement list and probably via Usenet.
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
Hints
|
|
Packit |
fc043f |
=====
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
To build for Windows you you may use the convenience command:
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
./autogen.sh --build-w32
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
which runs configure with suitable options. There is also basic
|
|
Packit |
fc043f |
support for building a 64 bit Windows version:
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
./autogen.sh --build-w64
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
Cross-Compiling
|
|
Packit |
fc043f |
===============
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
Libgpg-error needs to figure out some platform specific properties.
|
|
Packit |
fc043f |
These are used to build the platform specific gpg-error.h file. The
|
|
Packit |
fc043f |
detection is done during build time but can't be done when
|
|
Packit |
fc043f |
cross-compiling. Thus if you run into an error during building you
|
|
Packit |
fc043f |
need to figure out these values. You may use these commands:
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
build="$(build-aux/config.guess)"
|
|
Packit |
fc043f |
./configure --prefix=TARGETDIR --host=TARGET --build=$build
|
|
Packit |
fc043f |
cd src
|
|
Packit |
fc043f |
make gen-posix-lock-obj
|
|
Packit |
fc043f |
scp gen-posix-lock-obj TARGET:
|
|
Packit |
fc043f |
ssh TARGET ./gen-posix-lock-obj >tmp.h
|
|
Packit |
fc043f |
mv tmp.h "syscfg/$(awk 'NR==1 {print $2}' tmp.h)"
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
If you are using a VPATH build adjust accordingly. If this all works
|
|
Packit |
fc043f |
for you (make sure to run the test programs on the target platform),
|
|
Packit |
fc043f |
please send the generated file to the gnupg-devel mailing list so that
|
|
Packit |
fc043f |
we can include it in the next release. Note that in addition to the
|
|
Packit |
fc043f |
aliasing done by config.sub the src/mkheader build tool does some
|
|
Packit |
fc043f |
extra aliasing to avoid having too much identical syscfg files.
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
Known Problems
|
|
Packit |
fc043f |
==============
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
On Windows, WSA Error Codes can be provided as system error codes and
|
|
Packit |
fc043f |
will be transparently converted to the corresponding gpg error codes.
|
|
Packit |
fc043f |
There are two problems with this support:
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
* Not all error codes corresponding to WSA Error codes have a detailed
|
|
Packit |
fc043f |
description when printed with gpg_strerror. Some will default to
|
|
Packit |
fc043f |
"Unknown error" for pretty printing. For example, WSAEHOSTDOWN will
|
|
Packit |
fc043f |
be translated to GPG_ERR_EHOSTDOWN, but there is no corresponding
|
|
Packit |
fc043f |
EHOSTDOWN in Windows and thus gpg_strerror will default to "Unknown
|
|
Packit |
fc043f |
error" as printed by the system's strerror function for the argument
|
|
Packit |
fc043f |
WSAEHOSTDOWN. (This could be fixed by adding our own error strings
|
|
Packit |
fc043f |
replacing or extending the system error strings, including their
|
|
Packit |
fc043f |
translations).
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
* The translation to a gpg error code and back to a system error code
|
|
Packit |
fc043f |
in some cases does not preserve information. For example, the error
|
|
Packit |
fc043f |
code WSAEACCES translates to GPG_ERR_EACCES, which translates back
|
|
Packit |
fc043f |
to EACCES.
|
|
Packit |
fc043f |
|
|
Packit |
fc043f |
Any WSA Error code has either the first problem or the second (but not
|
|
Packit |
fc043f |
both), depending on if there is a corresponding Windows error code.
|