1 | /*============================================================================ |
2 | |
3 | WCSLIB 4.23 - an implementation of the FITS WCS standard. |
4 | Copyright (C) 1995-2014, Mark Calabretta |
5 | |
6 | This file is part of WCSLIB. |
7 | |
8 | WCSLIB is free software: you can redistribute it and/or modify it under the |
9 | terms of the GNU Lesser General Public License as published by the Free |
10 | Software Foundation, either version 3 of the License, or (at your option) |
11 | any later version. |
12 | |
13 | WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY |
14 | WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS |
15 | FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for |
16 | more details. |
17 | |
18 | You should have received a copy of the GNU Lesser General Public License |
19 | along with WCSLIB. If not, see http://www.gnu.org/licenses. |
20 | |
21 | Direct correspondence concerning WCSLIB to mark@calabretta.id.au |
22 | |
23 | Author: Mark Calabretta, Australia Telescope National Facility, CSIRO. |
24 | Module author: Michael Droettboom |
25 | http://www.atnf.csiro.au/people/Mark.Calabretta |
26 | $Id: wcserr.h,v 4.23 2014/05/13 05:50:51 mcalabre Exp $ |
27 | *============================================================================= |
28 | * |
29 | * Summary of the wcserr routines |
30 | * ------------------------------ |
31 | * Most of the structs in WCSLIB contain a pointer to a wcserr struct as a |
32 | * member. Functions in WCSLIB that return an error status code can also |
33 | * allocate and set a detailed error message in this struct which also |
34 | * identifies the function, source file, and line number where the error |
35 | * occurred. |
36 | * |
37 | * For example: |
38 | * |
39 | = struct prjprm prj; |
40 | = wcserr_enable(1); |
41 | = if (prjini(&prj)) { |
42 | = // Print the error message to stderr. |
43 | = wcsprintf_set(stderr); |
44 | = wcserr_prt(prj.err, 0x0); |
45 | = } |
46 | * |
47 | * A number of utility functions used in managing the wcserr struct are for |
48 | * internal use only. They are documented here solely as an aid to |
49 | * understanding the code. They are not intended for external use - the API |
50 | * may change without notice! |
51 | * |
52 | * |
53 | * wcserr struct - Error message handling |
54 | * -------------------------------------- |
55 | * The wcserr struct contains the numeric error code, a textual description of |
56 | * the error, and information about the function, source file, and line number |
57 | * where the error was generated. |
58 | * |
59 | * int status |
60 | * Numeric status code associated with the error, the meaning of which |
61 | * depends on the function that generated it. See the documentation for |
62 | * the particular function. |
63 | * |
64 | * int line_no |
65 | * Line number where the error occurred as given by the __LINE__ |
66 | * preprocessor macro. |
67 | * |
68 | * const char *function |
69 | * Name of the function where the error occurred. |
70 | * |
71 | * const char *file |
72 | * Name of the source file where the error occurred as given by the |
73 | * __FILE__ preprocessor macro. |
74 | * |
75 | * char msg[WCSERR_MSG_LENGTH] |
76 | * Informative error message. |
77 | * |
78 | * |
79 | * wcserr_enable() - Enable/disable error messaging |
80 | * ------------------------------------------------ |
81 | * wcserr_enable() enables or disables wcserr error messaging. By default it |
82 | * is disabled. |
83 | * |
84 | * PLEASE NOTE: This function is not thread-safe. |
85 | * |
86 | * Given: |
87 | * enable int If true (non-zero), enable error messaging, else |
88 | * disable it. |
89 | * |
90 | * Function return value: |
91 | * int Status return value: |
92 | * 0: Error messaging is disabled. |
93 | * 1: Error messaging is enabled. |
94 | * |
95 | * |
96 | * wcserr_prt() - Print a wcserr struct |
97 | * ------------------------------------ |
98 | * wcserr_prt() prints the error message (if any) contained in a wcserr struct. |
99 | * It uses the wcsprintf() functions. |
100 | * |
101 | * Given: |
102 | * err const struct wcserr* |
103 | * The error object. If NULL, nothing is printed. |
104 | * |
105 | * prefix const char * |
106 | * If non-NULL, each output line will be prefixed with |
107 | * this string. |
108 | * |
109 | * Function return value: |
110 | * int Status return value: |
111 | * 0: Success. |
112 | * 2: Error messaging is not enabled. |
113 | * |
114 | * |
115 | * wcserr_clear() - Clear a wcserr struct |
116 | * -------------------------------------- |
117 | * wcserr_clear() clears the error (if any) contained in a wcserr struct. |
118 | * |
119 | * Given and returned: |
120 | * err struct wcserr** |
121 | * The error object. If NULL, nothing is done. Set to |
122 | * NULL on return. |
123 | * |
124 | * Function return value: |
125 | * int Status return value: |
126 | * 0: Success. |
127 | * |
128 | * |
129 | * wcserr_set() - Fill in the contents of an error object |
130 | * ------------------------------------------------------ |
131 | * INTERNAL USE ONLY. |
132 | * |
133 | * wcserr_set() fills a wcserr struct with information about an error. |
134 | * |
135 | * A convenience macro, WCSERR_SET, provides the source file and line number |
136 | * information automatically. |
137 | * |
138 | * Given and returned: |
139 | * err struct wcserr** |
140 | * Error object. |
141 | * |
142 | * If err is NULL, returns the status code given without |
143 | * setting an error message. |
144 | * |
145 | * If *err is NULL, allocates memory for a wcserr struct |
146 | * (provided that status is non-zero). |
147 | * |
148 | * Given: |
149 | * status int Numeric status code to set. If 0, then *err will be |
150 | * deleted and *err will be returned as NULL. |
151 | * |
152 | * function const char * |
153 | * Name of the function generating the error. This |
154 | * must point to a constant string, i.e. in the |
155 | * initialized read-only data section ("data") of the |
156 | * executable. |
157 | * |
158 | * file const char * |
159 | * Name of the source file generating the error. This |
160 | * must point to a constant string, i.e. in the |
161 | * initialized read-only data section ("data") of the |
162 | * executable such as given by the __FILE__ preprocessor |
163 | * macro. |
164 | * |
165 | * line_no int Line number in the source file generating the error |
166 | * such as given by the __LINE__ preprocessor macro. |
167 | * |
168 | * format const char * |
169 | * Format string of the error message. May contain |
170 | * printf-style %-formatting codes. |
171 | * |
172 | * ... mixed The remaining variable arguments are applied (like |
173 | * printf) to the format string to generate the error |
174 | * message. |
175 | * |
176 | * Function return value: |
177 | * int The status return code passed in. |
178 | * |
179 | * |
180 | * wcserr_copy() - Copy an error object |
181 | * ------------------------------------ |
182 | * INTERNAL USE ONLY. |
183 | * |
184 | * wcserr_copy() copies one error object to another. Use of this function |
185 | * should be avoided in general since the function, source file, and line |
186 | * number information copied to the destination may lose its context. |
187 | * |
188 | * Given: |
189 | * src const struct wcserr* |
190 | * Source error object. If src is NULL, dst is cleared. |
191 | * |
192 | * Returned: |
193 | * dst struct wcserr* |
194 | * Destination error object. If NULL, no copy is made. |
195 | * |
196 | * Function return value: |
197 | * int Numeric status code of the source error object. |
198 | * |
199 | * |
200 | * WCSERR_SET() macro - Fill in the contents of an error object |
201 | * ------------------------------------------------------------ |
202 | * INTERNAL USE ONLY. |
203 | * |
204 | * WCSERR_SET() is a preprocessor macro that helps to fill in the argument list |
205 | * of wcserr_set(). It takes status as an argument of its own and provides the |
206 | * name of the source file and the line number at the point where invoked. It |
207 | * assumes that the err and function arguments of wcserr_set() will be provided |
208 | * by variables of the same names. |
209 | * |
210 | *===========================================================================*/ |
211 | |
212 | #ifndef WCSLIB_WCSERR |
213 | #define WCSLIB_WCSERR |
214 | |
215 | #ifdef __cplusplus |
216 | extern "C" { |
217 | #endif |
218 | |
219 | #define WCSERR_MSG_LENGTH 160 |
220 | |
221 | struct wcserr { |
222 | int status; /* Status code for the error. */ |
223 | int line_no; /* Line number where the error occurred. */ |
224 | const char *function; /* Function name. */ |
225 | const char *file; /* Source file name. */ |
226 | char msg[WCSERR_MSG_LENGTH]; /* Informative error message. */ |
227 | }; |
228 | |
229 | /* Size of the wcserr struct in int units, used by the Fortran wrappers. */ |
230 | #define ERRLEN (sizeof(struct wcserr)/sizeof(int)) |
231 | |
232 | int wcserr_enable(int enable); |
233 | |
234 | int wcserr_prt(const struct wcserr *err, const char *prefix); |
235 | |
236 | int wcserr_clear(struct wcserr **err); |
237 | |
238 | |
239 | /* INTERNAL USE ONLY -------------------------------------------------------*/ |
240 | |
241 | int wcserr_set(struct wcserr **err, int status, const char *function, |
242 | const char *file, int line_no, const char *format, ...); |
243 | |
244 | int wcserr_copy(const struct wcserr *src, struct wcserr *dst); |
245 | |
246 | /* Convenience macro for invoking wcserr_set(). */ |
247 | #define WCSERR_SET(status) err, status, function, __FILE__, __LINE__ |
248 | |
249 | #ifdef __cplusplus |
250 | } |
251 | #endif |
252 | |
253 | #endif /* WSCLIB_WCSERR */ |
254 | |