src/gpg-error.h.in

   1 /* gpg-error.h - Public interface to libgpg-error.               -*- c -*-
   2    Copyright (C) 2003, 2004, 2010, 2013, 2014 g10 Code GmbH
   3
   4    This file is part of libgpg-error.
   5
   6    libgpg-error is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU Lesser General Public License
   8    as published by the Free Software Foundation; either version 2.1 of
   9    the License, or (at your option) any later version.
  10
  11    libgpg-error is distributed in the hope that it will be useful, but
  12    WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with this program; if not, see <http://www.gnu.org/licenses/>.
  18
  19    @configure_input@
  20  */
  21
  22
  23 #ifndef GPG_ERROR_H
  24 #define GPG_ERROR_H     1
  25
  26 #include <stddef.h>
  27
  28 #ifdef __GNUC__
  29 #define GPG_ERR_INLINE __inline__
  30 #elif _MSC_VER >= 1300
  31 #define GPG_ERR_INLINE __inline
  32 #elif __STDC_VERSION__ >= 199901L
  33 #define GPG_ERR_INLINE inline
  34 #else
  35 #ifndef GPG_ERR_INLINE
  36 #define GPG_ERR_INLINE
  37 #endif
  38 #endif
  39
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #if 0 /* just to make Emacs auto-indent happy */
  44 }
  45 #endif
  46 #endif /* __cplusplus */
  47
  48 /* The GnuPG project consists of many components.  Error codes are
  49    exchanged between all components.  The common error codes and their
  50    user-presentable descriptions are kept into a shared library to
  51    allow adding new error codes and components without recompiling any
  52    of the other components.  The interface will not change in a
  53    backward incompatible way.
  54
  55    An error code together with an error source build up an error
  56    value.  As the error value is been passed from one component to
  57    another, it preserver the information about the source and nature
  58    of the error.
  59
  60    A component of the GnuPG project can define the following macros to
  61    tune the behaviour of the library:
  62
  63    GPG_ERR_SOURCE_DEFAULT: Define to an error source of type
  64    gpg_err_source_t to make that source the default for gpg_error().
  65    Otherwise GPG_ERR_SOURCE_UNKNOWN is used as default.
  66
  67    GPG_ERR_ENABLE_GETTEXT_MACROS: Define to provide macros to map the
  68    internal gettext API to standard names.  This has only an effect on
  69    Windows platforms.
  70
  71    In addition to the error codes, Libgpg-error also provides a set of
  72    functions used by most GnuPG components.  */
  73
  74 \f
  75 /* The error source type gpg_err_source_t.
  76
  77    Where as the Poo out of a welle small
  78    Taketh his firste springing and his sours.
  79                                         --Chaucer.  */
  80
  81 /* Only use free slots, never change or reorder the existing
  82    entries.  */
  83 typedef enum
  84   {
  85 @include:err-sources@
  86
  87     /* This is one more than the largest allowed entry.  */
  88     GPG_ERR_SOURCE_DIM = 128
  89   } gpg_err_source_t;
  90
  91 \f
  92 /* The error code type gpg_err_code_t.  */
  93
  94 /* Only use free slots, never change or reorder the existing
  95    entries.  */
  96 typedef enum
  97   {
  98 @include:err-codes@
  99
 100     /* The following error codes are used to map system errors.  */
 101 #define GPG_ERR_SYSTEM_ERROR    (1 << 15)
 102 @include:errnos@
 103
 104     /* This is one more than the largest allowed entry.  */
 105     GPG_ERR_CODE_DIM = 65536
 106   } gpg_err_code_t;
 107
 108 \f
 109 /* The error value type gpg_error_t.  */
 110
 111 /* We would really like to use bit-fields in a struct, but using
 112    structs as return values can cause binary compatibility issues, in
 113    particular if you want to do it effeciently (also see
 114    -freg-struct-return option to GCC).  */
 115 typedef unsigned int gpg_error_t;
 116
 117 /* We use the lowest 16 bits of gpg_error_t for error codes.  The 16th
 118    bit indicates system errors.  */
 119 #define GPG_ERR_CODE_MASK       (GPG_ERR_CODE_DIM - 1)
 120
 121 /* Bits 17 to 24 are reserved.  */
 122
 123 /* We use the upper 7 bits of gpg_error_t for error sources.  */
 124 #define GPG_ERR_SOURCE_MASK     (GPG_ERR_SOURCE_DIM - 1)
 125 #define GPG_ERR_SOURCE_SHIFT    24
 126
 127 /* The highest bit is reserved.  It shouldn't be used to prevent
 128    potential negative numbers when transmitting error values as
 129    text.  */
 130
 131 \f
 132 /* GCC feature test.  */
 133 #undef _GPG_ERR_HAVE_CONSTRUCTOR
 134 #if __GNUC__
 135 #define _GPG_ERR_GCC_VERSION (__GNUC__ * 10000 \
 136                             + __GNUC_MINOR__ * 100 \
 137                             + __GNUC_PATCHLEVEL__)
 138
 139 #if _GPG_ERR_GCC_VERSION > 30100
 140 #define _GPG_ERR_CONSTRUCTOR    __attribute__ ((__constructor__))
 141 #define _GPG_ERR_HAVE_CONSTRUCTOR
 142 #endif
 143 #endif
 144
 145 #ifndef _GPG_ERR_CONSTRUCTOR
 146 #define _GPG_ERR_CONSTRUCTOR
 147 #endif
 148
 149 \f
 150 /* Initialization function.  */
 151
 152 /* Initialize the library.  This function should be run early.  */
 153 gpg_error_t gpg_err_init (void) _GPG_ERR_CONSTRUCTOR;
 154
 155 /* If this is defined, the library is already initialized by the
 156    constructor and does not need to be initialized explicitely.  */
 157 #undef GPG_ERR_INITIALIZED
 158 #ifdef _GPG_ERR_HAVE_CONSTRUCTOR
 159 #define GPG_ERR_INITIALIZED     1
 160 #endif
 161
 162 /* See the source on how to use the deinit function; it is usually not
 163    required.  */
 164 void gpg_err_deinit (int mode);
 165
 166 \f
 167 /* Constructor and accessor functions.  */
 168
 169 /* Construct an error value from an error code and source.  Within a
 170    subsystem, use gpg_error.  */
 171 static GPG_ERR_INLINE gpg_error_t
 172 gpg_err_make (gpg_err_source_t source, gpg_err_code_t code)
 173 {
 174   return code == GPG_ERR_NO_ERROR ? GPG_ERR_NO_ERROR
 175     : (((source & GPG_ERR_SOURCE_MASK) << GPG_ERR_SOURCE_SHIFT)
 176        | (code & GPG_ERR_CODE_MASK));
 177 }
 178
 179
 180 /* The user should define GPG_ERR_SOURCE_DEFAULT before including this
 181    file to specify a default source for gpg_error.  */
 182 #ifndef GPG_ERR_SOURCE_DEFAULT
 183 #define GPG_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_UNKNOWN
 184 #endif
 185
 186 static GPG_ERR_INLINE gpg_error_t
 187 gpg_error (gpg_err_code_t code)
 188 {
 189   return gpg_err_make (GPG_ERR_SOURCE_DEFAULT, code);
 190 }
 191
 192
 193 /* Retrieve the error code from an error value.  */
 194 static GPG_ERR_INLINE gpg_err_code_t
 195 gpg_err_code (gpg_error_t err)
 196 {
 197   return (gpg_err_code_t) (err & GPG_ERR_CODE_MASK);
 198 }
 199
 200
 201 /* Retrieve the error source from an error value.  */
 202 static GPG_ERR_INLINE gpg_err_source_t
 203 gpg_err_source (gpg_error_t err)
 204 {
 205   return (gpg_err_source_t) ((err >> GPG_ERR_SOURCE_SHIFT)
 206                              & GPG_ERR_SOURCE_MASK);
 207 }
 208
 209 \f
 210 /* String functions.  */
 211
 212 /* Return a pointer to a string containing a description of the error
 213    code in the error value ERR.  This function is not thread-safe.  */
 214 const char *gpg_strerror (gpg_error_t err);
 215
 216 /* Return the error string for ERR in the user-supplied buffer BUF of
 217    size BUFLEN.  This function is, in contrast to gpg_strerror,
 218    thread-safe if a thread-safe strerror_r() function is provided by
 219    the system.  If the function succeeds, 0 is returned and BUF
 220    contains the string describing the error.  If the buffer was not
 221    large enough, ERANGE is returned and BUF contains as much of the
 222    beginning of the error string as fits into the buffer.  */
 223 int gpg_strerror_r (gpg_error_t err, char *buf, size_t buflen);
 224
 225 /* Return a pointer to a string containing a description of the error
 226    source in the error value ERR.  */
 227 const char *gpg_strsource (gpg_error_t err);
 228
 229 \f
 230 /* Mapping of system errors (errno).  */
 231
 232 /* Retrieve the error code for the system error ERR.  This returns
 233    GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
 234    this). */
 235 gpg_err_code_t gpg_err_code_from_errno (int err);
 236
 237
 238 /* Retrieve the system error for the error code CODE.  This returns 0
 239    if CODE is not a system error code.  */
 240 int gpg_err_code_to_errno (gpg_err_code_t code);
 241
 242
 243 /* Retrieve the error code directly from the ERRNO variable.  This
 244    returns GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped
 245    (report this) and GPG_ERR_MISSING_ERRNO if ERRNO has the value 0. */
 246 gpg_err_code_t gpg_err_code_from_syserror (void);
 247
 248
 249 /* Set the ERRNO variable.  This function is the preferred way to set
 250    ERRNO due to peculiarities on WindowsCE.  */
 251 void gpg_err_set_errno (int err);
 252
 253 /* Return or check the version.  */
 254 const char *gpg_error_check_version (const char *req_version);
 255
 256 /* The version string of this header. */
 257 #define GPG_ERROR_VERSION @version@
 258
 259 /* The version number of this header. */
 260 #define GPG_ERROR_VERSION_NUMBER @version-number@
 261
 262 @include:os-add@
 263 \f
 264 /* Self-documenting convenience functions.  */
 265
 266 static GPG_ERR_INLINE gpg_error_t
 267 gpg_err_make_from_errno (gpg_err_source_t source, int err)
 268 {
 269   return gpg_err_make (source, gpg_err_code_from_errno (err));
 270 }
 271
 272
 273 static GPG_ERR_INLINE gpg_error_t
 274 gpg_error_from_errno (int err)
 275 {
 276   return gpg_error (gpg_err_code_from_errno (err));
 277 }
 278
 279 static GPG_ERR_INLINE gpg_error_t
 280 gpg_error_from_syserror (void)
 281 {
 282   return gpg_error (gpg_err_code_from_syserror ());
 283 }
 284
 285
 286 \f
 287 /* Lock functions.  */
 288
 289 @include:lock-obj@
 290
 291 #define GPGRT_LOCK_DEFINE(name) \
 292   static gpgrt_lock_t name  = GPGRT_LOCK_INITIALIZER
 293
 294 /* NB: If GPGRT_LOCK_DEFINE is not used, zero out the lock variable
 295    before passing it to gpgrt_lock_init.  */
 296 gpg_err_code_t gpgrt_lock_init (gpgrt_lock_t *lockhd);
 297 gpg_err_code_t gpgrt_lock_lock (gpgrt_lock_t *lockhd);
 298 gpg_err_code_t gpgrt_lock_unlock (gpgrt_lock_t *lockhd);
 299 gpg_err_code_t gpgrt_lock_destroy (gpgrt_lock_t *lockhd);
 300
 301
 302 \f
 303 /* Thread functions.  */
 304
 305 gpg_err_code_t gpgrt_yield (void);
 306
 307
 308
 309 \f
 310 /* Estream */
 311
 312
 313
 314 #ifdef __cplusplus
 315 }
 316 #endif
 317 #endif  /* GPG_ERROR_H */