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