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

0001 What is Libgpg-error
0002 ====================
0003 
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
0010 
0011  - Structured error codes and utility functions.
0012 
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_")
0017 
0018  - Generic Mutex implementation for all platforms using an ABI
0019    independent of the underlying implementation.
0020 
0021  - A lean gettext and iconv implementation for Windows.
0022 
0023  - Log functions
0024 
0025  - Option parser
0026 
0027  - Base-64 encoder and decoder.
0028 
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.
0032 
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.
0039 
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.
0047 
0048 
0049 Installation
0050 ============
0051 
0052 Please read the file INSTALL!
0053 
0054 Here is a quick summary:
0055 
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!
0059 
0060 2) Unpack the archive.  With GNU tar you can do it this way:
0061    "tar xjvf libgpg-error-x.y.tar.bz2"
0062 
0063 3) "cd libgpg-error-x.y"
0064 
0065 4) "./configure"
0066 
0067 5) "make"
0068 
0069 6) "make install"
0070 
0071 
0072 How to Verify the Source
0073 ========================
0074 
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:
0078 
0079 a) If you already have a trusted version of GnuPG installed, you can
0080    simply check the supplied signature:
0081 
0082    $ gpg --verify libgpg-error-x.y.tar.bz2.sig libgpg-error-x.y.tar.bz2
0083 
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.
0087 
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!
0091 
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:
0095 
0096    $ sha1sum libgpg-error-x.y.tar.bz2
0097 
0098    This should yield an output _similar_ to this:
0099 
0100    610064e5b77700f5771c8fde2691c4365e1ca100  libgpg-error-x.y.tar.bz2
0101 
0102    Now check that this checksum is _exactly_ the same as the one
0103    published via the announcement list and probably via Usenet.
0104 
0105 
0106 Hints
0107 =====
0108 
0109 To build for Windows you you may use the convenience command:
0110 
0111    ./autogen.sh --build-w32
0112 
0113 which runs configure with suitable options.  There is also basic
0114 support for building a 64 bit Windows version:
0115 
0116    ./autogen.sh --build-w64
0117 
0118 
0119 Cross-Compiling
0120 ===============
0121 
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:
0127 
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)"
0135 
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.
0142 
0143 
0144 
0145 Known Problems
0146 ==============
0147 
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:
0151 
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).
0161 
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.
0166 
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.