WCSLIB
7.3.1
C
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.
Generated on Thu Aug 27 2020 22:46:49 for WCSLIB by
1.8.18