WCSLIB 8.4

Loading...
Searching...
No Matches
wcserr.h
Go to the documentation of this file.
1/*============================================================================
2 WCSLIB 8.4 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2024, 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.4 2024/10/28 13:56:16 mcalabre Exp $
24*=============================================================================
25*
26* WCSLIB 8.4 - 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
wcserr
Error message handling.
Definition wcserr.h:243
wcserr::line_no
int line_no
Definition wcserr.h:245
wcserr::file
const char * file
Definition wcserr.h:247
wcserr::msg
char * msg
Definition wcserr.h:248
wcserr::function
const char * function
Definition wcserr.h:246
wcserr::status
int status
Definition wcserr.h:244
wcserr_enable
int wcserr_enable(int enable)
Enable/disable error messaging.
wcserr_prt
int wcserr_prt(const struct wcserr *err, const char *prefix)
Print a wcserr struct.
wcserr_clear
int wcserr_clear(struct wcserr **err)
Clear a wcserr struct.
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_copy
int wcserr_copy(const struct wcserr *src, struct wcserr *dst)
Copy an error object.
wcserr_size
int wcserr_size(const struct wcserr *err, int sizes[2])
Compute the size of a wcserr struct.