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