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