00001 /*============================================================================ 00002 00003 WCSLIB 4.15 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2012, Mark Calabretta 00005 00006 This file is part of WCSLIB. 00007 00008 WCSLIB is free software: you can redistribute it and/or modify it under the 00009 terms of the GNU Lesser General Public License as published by the Free 00010 Software Foundation, either version 3 of the License, or (at your option) 00011 any later version. 00012 00013 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY 00014 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00015 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for 00016 more details. 00017 00018 You should have received a copy of the GNU Lesser General Public License 00019 along with WCSLIB. If not, see http://www.gnu.org/licenses. 00020 00021 Direct correspondence concerning WCSLIB to mark@calabretta.id.au 00022 00023 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO. 00024 Module author: Michael Droettboom 00025 http://www.atnf.csiro.au/people/Mark.Calabretta 00026 $Id: wcserr.h,v 4.15 2012/09/26 14:26:05 cal103 Exp $ 00027 *============================================================================= 00028 * 00029 * Summary of the wcserr routines 00030 * ------------------------------ 00031 * Most of the structs in WCSLIB contain a pointer to a wcserr struct as a 00032 * member. Functions in WCSLIB that return an error status code can also 00033 * allocate and set a detailed error message in this struct which also 00034 * identifies the function, source file, and line number where the error 00035 * occurred. 00036 * 00037 * For example: 00038 * 00039 = struct prjprm prj; 00040 = wcserr_enable(1); 00041 = if (prjini(&prj)) { 00042 = // Print the error message to stderr. 00043 = wcsprintf_set(stderr); 00044 = wcserr_prt(prj.err, 0x0); 00045 = } 00046 * 00047 * A number of utility functions used in managing the wcserr struct are for 00048 * internal use only. They are documented here solely as an aid to 00049 * understanding the code. They are not intended for external use - the API 00050 * may change without notice! 00051 * 00052 * 00053 * wcserr struct - Error message handling 00054 * -------------------------------------- 00055 * The wcserr struct contains the numeric error code, a textual description of 00056 * the error, and information about the function, source file, and line number 00057 * where the error was generated. 00058 * 00059 * int status 00060 * Numeric status code associated with the error, the meaning of which 00061 * depends on the function that generated it. See the documentation for 00062 * the particular function. 00063 * 00064 * int line_no 00065 * Line number where the error occurred as given by the __LINE__ 00066 * preprocessor macro. 00067 * 00068 * const char *function 00069 * Name of the function where the error occurred. 00070 * 00071 * const char *file 00072 * Name of the source file where the error occurred as given by the 00073 * __FILE__ preprocessor macro. 00074 * 00075 * char msg[WCSERR_MSG_LENGTH] 00076 * Informative error message. 00077 * 00078 * 00079 * wcserr_enable() - Enable/disable error messaging 00080 * ------------------------------------------------ 00081 * wcserr_enable() enables or disables wcserr error messaging. By default it 00082 * is disabled. 00083 * 00084 * PLEASE NOTE: This function is not thread-safe. 00085 * 00086 * Given: 00087 * enable int If true (non-zero), enable error messaging, else 00088 * disable it. 00089 * 00090 * Function return value: 00091 * int Status return value: 00092 * 0: Error messaging is disabled. 00093 * 1: Error messaging is enabled. 00094 * 00095 * 00096 * wcserr_prt() - Print a wcserr struct 00097 * ------------------------------------ 00098 * wcserr_prt() prints the error message (if any) contained in a wcserr struct. 00099 * It uses the wcsprintf() functions. 00100 * 00101 * Given: 00102 * err const struct wcserr* 00103 * The error object. If NULL, nothing is printed. 00104 * 00105 * prefix const char * 00106 * If non-NULL, each output line will be prefixed with 00107 * this string. 00108 * 00109 * Function return value: 00110 * int Status return value: 00111 * 0: Success. 00112 * 2: Error messaging is not enabled. 00113 * 00114 * 00115 * wcserr_clear() - Clear a wcserr struct 00116 * -------------------------------------- 00117 * wcserr_clear() clears the error (if any) contained in a wcserr struct. 00118 * 00119 * Given and returned: 00120 * err struct wcserr** 00121 * The error object. If NULL, nothing is done. Set to 00122 * NULL on return. 00123 * 00124 * Function return value: 00125 * int Status return value: 00126 * 0: Success. 00127 * 00128 * 00129 * wcserr_set() - Fill in the contents of an error object 00130 * ------------------------------------------------------ 00131 * INTERNAL USE ONLY. 00132 * 00133 * wcserr_set() fills a wcserr struct with information about an error. 00134 * 00135 * A convenience macro, WCSERR_SET, provides the source file and line number 00136 * information automatically. 00137 * 00138 * Given and returned: 00139 * err struct wcserr** 00140 * Error object. 00141 * 00142 * If err is NULL, returns the status code given without 00143 * setting an error message. 00144 * 00145 * If *err is NULL, allocates memory for a wcserr struct 00146 * (provided that status is non-zero). 00147 * 00148 * Given: 00149 * status int Numeric status code to set. If 0, then *err will be 00150 * deleted and *err will be returned as NULL. 00151 * 00152 * function const char * 00153 * Name of the function generating the error. This 00154 * must point to a constant string, i.e. in the 00155 * initialized read-only data section ("data") of the 00156 * executable. 00157 * 00158 * file const char * 00159 * Name of the source file generating the error. This 00160 * must point to a constant string, i.e. in the 00161 * initialized read-only data section ("data") of the 00162 * executable such as given by the __FILE__ preprocessor 00163 * macro. 00164 * 00165 * line_no int Line number in the source file generating the error 00166 * such as given by the __LINE__ preprocessor macro. 00167 * 00168 * format const char * 00169 * Format string of the error message. May contain 00170 * printf-style %-formatting codes. 00171 * 00172 * ... mixed The remaining variable arguments are applied (like 00173 * printf) to the format string to generate the error 00174 * message. 00175 * 00176 * Function return value: 00177 * int The status return code passed in. 00178 * 00179 * 00180 * wcserr_copy() - Copy an error object 00181 * ------------------------------------ 00182 * INTERNAL USE ONLY. 00183 * 00184 * wcserr_copy() copies one error object to another. Use of this function 00185 * should be avoided in general since the function, source file, and line 00186 * number information copied to the destination may lose its context. 00187 * 00188 * Given: 00189 * src const struct wcserr* 00190 * Source error object. If src is NULL, dst is cleared. 00191 * 00192 * Returned: 00193 * dst struct wcserr* 00194 * Destination error object. If NULL, no copy is made. 00195 * 00196 * Function return value: 00197 * int Numeric status code of the source error object. 00198 * 00199 * 00200 * WCSERR_SET() macro - Fill in the contents of an error object 00201 * ------------------------------------------------------------ 00202 * INTERNAL USE ONLY. 00203 * 00204 * WCSERR_SET() is a preprocessor macro that helps to fill in the argument list 00205 * of wcserr_set(). It takes status as an argument of its own and provides the 00206 * name of the source file and the line number at the point where invoked. It 00207 * assumes that the err and function arguments of wcserr_set() will be provided 00208 * by variables of the same names. 00209 * 00210 *===========================================================================*/ 00211 00212 #ifndef WCSLIB_WCSERR 00213 #define WCSLIB_WCSERR 00214 00215 #define WCSERR_MSG_LENGTH 160 00216 00217 struct wcserr { 00218 int status; /* Status code for the error. */ 00219 int line_no; /* Line number where the error occurred. */ 00220 const char *function; /* Function name. */ 00221 const char *file; /* Source file name. */ 00222 char msg[WCSERR_MSG_LENGTH]; /* Informative error message. */ 00223 }; 00224 00225 /* Size of the wcserr struct in int units, used by the Fortran wrappers. */ 00226 #define ERRLEN (sizeof(struct wcserr)/sizeof(int)) 00227 00228 int wcserr_enable(int enable); 00229 00230 int wcserr_prt(const struct wcserr *err, const char *prefix); 00231 00232 int wcserr_clear(struct wcserr **err); 00233 00234 00235 /* INTERNAL USE ONLY -------------------------------------------------------*/ 00236 00237 int wcserr_set(struct wcserr **err, int status, const char *function, 00238 const char *file, int line_no, const char *format, ...); 00239 00240 int wcserr_copy(const struct wcserr *src, struct wcserr *dst); 00241 00242 /* Convenience macro for invoking wcserr_set(). */ 00243 #define WCSERR_SET(status) err, status, function, __FILE__, __LINE__ 00244 00245 #endif /* WSCLIB_WCSERR */