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