WCSLIB 4.20
wcserr.h
Go to the documentation of this file.
1 /*============================================================================
2 
3  WCSLIB 4.20 - an implementation of the FITS WCS standard.
4  Copyright (C) 1995-2013, 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_8h_source.html,v 1.1 2014/02/12 21:11:37 irby 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
216 extern "C" {
217 #endif
218 
219 #define WCSERR_MSG_LENGTH 160
220 
221 struct 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 
232 int wcserr_enable(int enable);
233 
234 int wcserr_prt(const struct wcserr *err, const char *prefix);
235 
236 int wcserr_clear(struct wcserr **err);
237 
238 
239 /* INTERNAL USE ONLY -------------------------------------------------------*/
240 
241 int wcserr_set(struct wcserr **err, int status, const char *function,
242  const char *file, int line_no, const char *format, ...);
243 
244 int 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 */
Generated on Wed Dec 18 2013 16:43:14 for WCSLIB 4.20 by   doxygen 1.8.4