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