WCSLIB
7.3
C
wcserr.h
Go to the documentation of this file.
1
/*============================================================================
2
3
WCSLIB 7.3 - an implementation of the FITS WCS standard.
4
Copyright (C) 1995-2020, 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 7.3 2020/06/03 03:37:02 mcalabre Exp $
27
*=============================================================================
28
*
29
* WCSLIB 7.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_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:225
wcserr_clear
int wcserr_clear(struct wcserr **err)
Clear a wcserr struct.
wcserr::file
const char * file
Definition:
wcserr.h:227
wcserr::status
int status
Definition:
wcserr.h:224
wcserr::msg
char * msg
Definition:
wcserr.h:228
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:223
wcserr_prt
int wcserr_prt(const struct wcserr *err, const char *prefix)
Print a wcserr struct.
Generated on Wed Jun 3 2020 13:37:27 for WCSLIB by
1.8.18