- Main Page
- Related Pages
- Data Structures
- Files

# wcserr.h

Go to the documentation of this file.

    00001 /*============================================================================
    00002
    00003   WCSLIB 4.13 - an implementation of the FITS WCS standard.
    00004   Copyright (C) 1995-2012, Mark Calabretta
    00005
    00006   This file is part of WCSLIB.
    00007
    00008   WCSLIB is free software: you can redistribute it and/or modify it under the
    00009   terms of the GNU Lesser General Public License as published by the Free
    00010   Software Foundation, either version 3 of the License, or (at your option)
    00011   any later version.
    00012
    00013   WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
    00014   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    00015   FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
    00016   more details.
    00017
    00018   You should have received a copy of the GNU Lesser General Public License
    00019   along with WCSLIB.  If not, see <http://www.gnu.org/licenses/>.
    00020
    00021   Correspondence concerning WCSLIB may be directed to:
    00022     Internet email: mcalabre@atnf.csiro.au
    00023     Postal address: Dr. Mark Calabretta
    00024                     Australia Telescope National Facility, CSIRO
    00025                     PO Box 76
    00026                     Epping NSW 1710
    00027                     AUSTRALIA
    00028
    00029   Author: Mark Calabretta, Australia Telescope National Facility
    00030   Module author: Michael Droettboom
    00031   http://www.atnf.csiro.au/~mcalabre/index.html
    00032   $Id: wcserr.h,v 4.13.1.1 2012/03/14 07:40:37 cal103 Exp cal103 $
    00033 *=============================================================================
    00034 *
    00035 * Summary of the wcserr routines
    00036 * ------------------------------
    00037 * Most of the structs in WCSLIB contain a pointer to a wcserr struct as a
    00038 * member.  Functions in WCSLIB that return an error status code can also
    00039 * allocate and set a detailed error message in this struct which also
    00040 * identifies the function, source file, and line number where the error
    00041 * occurred.
    00042 *
    00043 * For example:
    00044 *
    00045 =     struct prjprm prj;
    00046 =     wcserr_enable(1);
    00047 =     if (prjini(&prj)) {
    00048 =       // Print the error message to stderr.
    00049 =       wcsprintf_set(stderr);
    00050 =       wcserr_prt(prj.err, 0x0);
    00051 =     }
    00052 *
    00053 * A number of utility functions used in managing the wcserr struct are for
    00054 * internal use only.  They are documented here solely as an aid to
    00055 * understanding the code.  They are not intended for external use - the API
    00056 * may change without notice!
    00057 *
    00058 *
    00059 * wcserr struct - Error message handling
    00060 * --------------------------------------
    00061 * The wcserr struct contains the numeric error code, a textual description of
    00062 * the error, and information about the function, source file, and line number
    00063 * where the error was generated.
    00064 *
    00065 *   int status
    00066 *     Numeric status code associated with the error, the meaning of which
    00067 *     depends on the function that generated it.  See the documentation for
    00068 *     the particular function.
    00069 *
    00070 *   int line_no
    00071 *     Line number where the error occurred as given by the __LINE__
    00072 *     preprocessor macro.
    00073 *
    00074 *   const char *function
    00075 *     Name of the function where the error occurred.
    00076 *
    00077 *   const char *file
    00078 *     Name of the source file where the error occurred as given by the
    00079 *     __FILE__ preprocessor macro.
    00080 *
    00081 *   char msg[WCSERR_MSG_LENGTH]
    00082 *     Informative error message.
    00083 *
    00084 *
    00085 * wcserr_enable() - Enable/disable error messaging
    00086 * ------------------------------------------------
    00087 * wcserr_enable() enables or disables wcserr error messaging.  By default it
    00088 * is disabled.
    00089 *
    00090 * PLEASE NOTE: This function is not thread-safe.
    00091 *
    00092 * Given:
    00093 *   enable    int       If true (non-zero), enable error messaging, else
    00094 *                       disable it.
    00095 *
    00096 * Function return value:
    00097 *             int       Status return value:
    00098 *                         0: Error messaging is disabled.
    00099 *                         1: Error messaging is enabled.
    00100 *
    00101 *
    00102 * wcserr_prt() - Print a wcserr struct
    00103 * ------------------------------------
    00104 * wcserr_prt() prints the error message (if any) contained in a wcserr struct.
    00105 * It uses the wcsprintf() functions.
    00106 *
    00107 * Given:
    00108 *   err       const struct wcserr*
    00109 *                       The error object.  If NULL, nothing is printed.
    00110 *
    00111 *   prefix    const char *
    00112 *                       If non-NULL, each output line will be prefixed with
    00113 *                       this string.
    00114 *
    00115 * Function return value:
    00116 *             int       Status return value:
    00117 *                         0: Success.
    00118 *                         2: Error messaging is not enabled.
    00119 *
    00120 *
    00121 * wcserr_clear() - Clear a wcserr struct
    00122 * --------------------------------------
    00123 * wcserr_clear() clears the error (if any) contained in a wcserr struct.
    00124 *
    00125 * Given and returned:
    00126 *   err       struct wcserr**
    00127 *                       The error object.  If NULL, nothing is done.  Set to
    00128 *                       NULL on return.
    00129 *
    00130 * Function return value:
    00131 *             int       Status return value:
    00132 *                         0: Success.
    00133 *
    00134 *
    00135 * wcserr_set() - Fill in the contents of an error object
    00136 * ------------------------------------------------------
    00137 * INTERNAL USE ONLY.
    00138 *
    00139 * wcserr_set() fills a wcserr struct with information about an error.
    00140 *
    00141 * A convenience macro, WCSERR_SET, provides the source file and line number
    00142 * information automatically.
    00143 *
    00144 * Given and returned:
    00145 *   err       struct wcserr**
    00146 *                       Error object.
    00147 *
    00148 *                       If err is NULL, returns the status code given without
    00149 *                       setting an error message.
    00150 *
    00151 *                       If *err is NULL, allocates memory for a wcserr struct
    00152 *                       (provided that status is non-zero).
    00153 *
    00154 * Given:
    00155 *   status    int       Numeric status code to set.  If 0, then *err will be
    00156 *                       deleted and *err will be returned as NULL.
    00157 *
    00158 *   function  const char *
    00159 *                       Name of the function generating the error.  This
    00160 *                       must point to a constant string, i.e. in the
    00161 *                       initialized read-only data section ("data") of the
    00162 *                       executable.
    00163 *
    00164 *   file      const char *
    00165 *                       Name of the source file generating the error.  This
    00166 *                       must point to a constant string, i.e. in the
    00167 *                       initialized read-only data section ("data") of the
    00168 *                       executable such as given by the __FILE__ preprocessor
    00169 *                       macro.
    00170 *
    00171 *   line_no   int       Line number in the source file generating the error
    00172 *                       such as given by the __LINE__ preprocessor macro.
    00173 *
    00174 *   format    const char *
    00175 *                       Format string of the error message.  May contain
    00176 *                       printf-style %-formatting codes.
    00177 *
    00178 *   ...       mixed     The remaining variable arguments are applied (like
    00179 *                       printf) to the format string to generate the error
    00180 *                       message.
    00181 *
    00182 * Function return value:
    00183 *             int       The status return code passed in.
    00184 *
    00185 *
    00186 * wcserr_copy() - Copy an error object
    00187 * ------------------------------------
    00188 * INTERNAL USE ONLY.
    00189 *
    00190 * wcserr_copy() copies one error object to another.  Use of this function
    00191 * should be avoided in general since the function, source file, and line
    00192 * number information copied to the destination may lose its context.
    00193 *
    00194 * Given:
    00195 *   src       const struct wcserr*
    00196 *                       Source error object.  If src is NULL, dst is cleared.
    00197 *
    00198 * Returned:
    00199 *   dst       struct wcserr*
    00200 *                       Destination error object.  If NULL, no copy is made.
    00201 *
    00202 * Function return value:
    00203 *             int       Numeric status code of the source error object.
    00204 *
    00205 *
    00206 * WCSERR_SET() macro - Fill in the contents of an error object
    00207 * ------------------------------------------------------------
    00208 * INTERNAL USE ONLY.
    00209 *
    00210 * WCSERR_SET() is a preprocessor macro that helps to fill in the argument list
    00211 * of wcserr_set().  It takes status as an argument of its own and provides the
    00212 * name of the source file and the line number at the point where invoked.  It
    00213 * assumes that the err and function arguments of wcserr_set() will be provided
    00214 * by variables of the same names.
    00215 *
    00216 *===========================================================================*/
    00217
    00218 #ifndef WCSLIB_WCSERR
    00219 #define WCSLIB_WCSERR
    00220
    00221 #define WCSERR_MSG_LENGTH 160
    00222
    00223 struct wcserr {
    00224   int  status;                  /* Status code for the error.               */
    00225   int  line_no;                 /* Line number where the error occurred.    */
    00226   const char *function;         /* Function name.                           */
    00227   const char *file;             /* Source file name.                        */
    00228   char msg[WCSERR_MSG_LENGTH];  /* Informative error message.               */
    00229 };
    00230
    00231 /* Size of the wcserr struct in int units, used by the Fortran wrappers. */
    00232 #define ERRLEN (sizeof(struct wcserr)/sizeof(int))
    00233
    00234 int wcserr_enable(int enable);
    00235
    00236 int wcserr_prt(const struct wcserr *err, const char *prefix);
    00237
    00238 int wcserr_clear(struct wcserr **err);
    00239
    00240
    00241 /* INTERNAL USE ONLY -------------------------------------------------------*/
    00242
    00243 int wcserr_set(struct wcserr **err, int status, const char *function,
    00244   const char *file, int line_no, const char *format, ...);
    00245
    00246 int wcserr_copy(const struct wcserr *src, struct wcserr *dst);
    00247
    00248 /* Convenience macro for invoking wcserr_set(). */
    00249 #define WCSERR_SET(status) err, status, function, __FILE__, __LINE__
    00250
    00251 #endif /* WSCLIB_WCSERR */