- Main Page
- Related Pages
- Data Structures
- Files

# wcserr.h

Go to the documentation of this file.

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