WCSLIB: wcserr.h Source File

WCSLIB 6.3

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