Warning, /libgpg-error/README is written in an unsupported language. File is not indexed.

0001 What is Libgpg-error
0002 ====================
0004 Libgpg-error is a library that defines common error values for all
0005 GnuPG components.  Among these are GPG, GPGSM, GPGME, GPG-Agent,
0006 libgcrypt, Libksba, DirMngr, Pinentry, SmartCard Daemon and more.
0007 Meanwhile Libgcrypt also sports functions commonly used by all GnuPG
0008 components and which are believed to be generally useful.  The main
0009 components are
0011  - Structured error codes and utility functions.
0013  - Replacement functions for stdio stream (estream) to provide a
0014    reliable set of printf features on all platforms.  For convenience
0015    macros are provided to make migration from stdio to estream easier
0016    (ie. the prefix "es_")
0018  - Generic Mutex implementation for all platforms using an ABI
0019    independent of the underlying implementation.
0021  - A lean gettext and iconv implementation for Windows.
0023  - Log functions
0025  - Option parser
0027  - Base-64 encoder and decoder.
0029 More components will be added over time.  Most functions are prefixed
0030 with "gpgrt" (GnuPG Run Time) instead of "gpg_err" to indicate the
0031 long term plan to rename this library to gpgrt.
0033 Libgpg-error is free software; you can redistribute it and/or modify
0034 it under the terms of the GNU Lesser General Public License as
0035 published by the Free Software Foundation; either version 2.1 of the
0036 License, or (at your option) any later version.  See the file
0037 COPYING.LIB for copyright and warranty information.  See the file
0038 AUTHORS for a list of authors and important mail addresses.
0040 However, some files (for example src/mkerrnos.awk) used in the build
0041 process of the library and the manual are covered by a different
0042 license.  Please see the header of these files and the file COPYING
0043 for copyright and warranty information on these files.  A special
0044 exception in the copyright license of these files makes sure that the
0045 output in the build process, which is used in libgpg-error, is not
0046 affected by the GPL.
0049 Installation
0050 ============
0052 Please read the file INSTALL!
0054 Here is a quick summary:
0056 1) Check that you have unmodified sources.  You can find instructions
0057    how to verify the sources below.  Don't skip this - it is an
0058    important step!
0060 2) Unpack the archive.  With GNU tar you can do it this way:
0061    "tar xjvf libgpg-error-x.y.tar.bz2"
0063 3) "cd libgpg-error-x.y"
0065 4) "./configure"
0067 5) "make"
0069 6) "make install"
0072 How to Verify the Source
0073 ========================
0075 In order to check that the version of libgpg-error which you are going
0076 to install is an original and unmodified copy of the original, you can
0077 do it in one of the following ways:
0079 a) If you already have a trusted version of GnuPG installed, you can
0080    simply check the supplied signature:
0082    $ gpg --verify libgpg-error-x.y.tar.bz2.sig libgpg-error-x.y.tar.bz2
0084    This checks that the detached signature libgpg-error-x.y.tar.bz2.sig
0085    is indeed a signature of libgpg-error-x.y.tar.bz2.  Make sure that
0086    the signature has been created by a trusted keys.
0088    Please note that you have to use an old version of GnuPG to do all
0089    this stuff.  *Never* use the version which was built using the
0090    library you are trying to verify!
0092 b) If you don't have any a trusted version of GnuPG, you can attempt
0093    to verify the SHA1 checksum, using a trusted version of the sha1sum
0094    program:
0096    $ sha1sum libgpg-error-x.y.tar.bz2
0098    This should yield an output _similar_ to this:
0100    610064e5b77700f5771c8fde2691c4365e1ca100  libgpg-error-x.y.tar.bz2
0102    Now check that this checksum is _exactly_ the same as the one
0103    published via the announcement list and probably via Usenet.
0106 Hints
0107 =====
0109 To build for Windows you you may use the convenience command:
0111    ./autogen.sh --build-w32
0113 which runs configure with suitable options.  There is also basic
0114 support for building a 64 bit Windows version:
0116    ./autogen.sh --build-w64
0119 Cross-Compiling
0120 ===============
0122 Libgpg-error needs to figure out some platform specific properties.
0123 These are used to build the platform specific gpg-error.h file.  The
0124 detection is done during build time but can't be done when
0125 cross-compiling.  Thus if you run into an error during building you
0126 need to figure out these values.  You may use these commands:
0128   build="$(build-aux/config.guess)"
0129   ./configure --prefix=TARGETDIR --host=TARGET --build=$build
0130   cd src
0131   make gen-posix-lock-obj
0132   scp gen-posix-lock-obj TARGET:
0133   ssh TARGET ./gen-posix-lock-obj >tmp.h
0134   mv tmp.h "syscfg/$(awk 'NR==1 {print $2}' tmp.h)"
0136 If you are using a VPATH build adjust accordingly.  If this all works
0137 for you (make sure to run the test programs on the target platform),
0138 please send the generated file to the gnupg-devel mailing list so that
0139 we can include it in the next release.  Note that in addition to the
0140 aliasing done by config.sub the src/mkheader build tool does some
0141 extra aliasing to avoid having too much identical syscfg files.
0145 Known Problems
0146 ==============
0148 On Windows, WSA Error Codes can be provided as system error codes and
0149 will be transparently converted to the corresponding gpg error codes.
0150 There are two problems with this support:
0152 * Not all error codes corresponding to WSA Error codes have a detailed
0153   description when printed with gpg_strerror.  Some will default to
0154   "Unknown error" for pretty printing.  For example, WSAEHOSTDOWN will
0155   be translated to GPG_ERR_EHOSTDOWN, but there is no corresponding
0156   EHOSTDOWN in Windows and thus gpg_strerror will default to "Unknown
0157   error" as printed by the system's strerror function for the argument
0158   WSAEHOSTDOWN.  (This could be fixed by adding our own error strings
0159   replacing or extending the system error strings, including their
0160   translations).
0162 * The translation to a gpg error code and back to a system error code
0163   in some cases does not preserve information.  For example, the error
0164   code WSAEACCES translates to GPG_ERR_EACCES, which translates back
0165   to EACCES.
0167 Any WSA Error code has either the first problem or the second (but not
0168 both), depending on if there is a corresponding Windows error code.