src/gromacs/utility/fatalerror.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
   5  * Copyright (c) 2001-2004, The GROMACS development team.
   6  * Copyright (c) 2012,2014, by the GROMACS development team, led by
   7  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   8  * and including many others, as listed in the AUTHORS file in the
   9  * top-level source directory and at http://www.gromacs.org.
  10  *
  11  * GROMACS is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Lesser General Public License
  13  * as published by the Free Software Foundation; either version 2.1
  14  * of the License, or (at your option) any later version.
  15  *
  16  * GROMACS is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public
  22  * License along with GROMACS; if not, see
  23  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  24  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  25  *
  26  * If you want to redistribute modifications to GROMACS, please
  27  * consider that scientific software is very special. Version
  28  * control is crucial - bugs must be traceable. We will be happy to
  29  * consider code for inclusion in the official distribution, but
  30  * derived work must not be called official GROMACS. Details are found
  31  * in the README & COPYING files - if they are missing, get the
  32  * official version at http://www.gromacs.org.
  33  *
  34  * To help us fund GROMACS development, we humbly ask that you cite
  35  * the research papers on the package. Check out http://www.gromacs.org.
  36  */
  37 /*! \file
  38  * \brief
  39  * Declares fatal error handling and debugging routines for C code.
  40  *
  41  * \inpublicapi
  42  * \ingroup module_utility
  43  */
  44 #ifndef GMX_UTILITY_FATALERROR_H
  45 #define GMX_UTILITY_FATALERROR_H
  46
  47 #include <stdio.h>
  48
  49 #include "../legacyheaders/types/simple.h"
  50
  51 #ifdef __cplusplus
  52 extern "C" {
  53 #endif
  54
  55 #ifndef __has_feature
  56 /** For compatibility with non-clang compilers. */
  57 #define __has_feature(x) 0
  58 #endif
  59
  60 /*! \def GMX_ATTRIBUTE_NORETURN
  61  * \brief
  62  * Indicate that a function is not expected to return.
  63  *
  64  * \todo
  65  * There are functions outside this header that need the same attribute.
  66  * This could be moved to a generic header and made it affect also compiler
  67  * code generation.
  68  */
  69 #ifndef GMX_ATTRIBUTE_NORETURN
  70 #if __has_feature(attribute_analyzer_noreturn)
  71 #define GMX_ATTRIBUTE_NORETURN __attribute__((analyzer_noreturn))
  72 #else
  73 #define GMX_ATTRIBUTE_NORETURN
  74 #endif
  75 #endif
  76
  77 /** Implementation for where(). */
  78 void
  79 _where(const char *file, int line);
  80 /** Prints filename and line to stdlog. */
  81 #define where() _where(__FILE__, __LINE__)
  82
  83 /*! \brief
  84  * Fatal error reporting routine for \Gromacs.
  85  *
  86  * This function prints a fatal error message with a header that contains the
  87  * source file and line number of the call, followed by the string specified by
  88  * \p fmt and supplied parameters.
  89  * If \p fatal_errno is 0, only the message and arguments are printed.
  90  * If \p fatal_errno is a legal system errno or -1, a perror()-like message is
  91  * printed after the first message; if fatal_errno is -1, the last system errno
  92  * will be used.
  93  * The format of \p fmt uses printf()-like formatting.
  94  *
  95  * In case all MPI processes want to stop with the same fatal error,
  96  * use gmx_fatal_collective(), declared in gmx_fatal_collective.h,
  97  * to avoid having as many error messages as processes.
  98  *
  99  * The first three parameters can be provided through ::FARGS:
 100  * \code
 101    gmx_fatal(FARGS, fmt, ...);
 102    \endcode
 103  */
 104 void
 105 gmx_fatal(int fatal_errno, const char *file, int line, const char *fmt, ...) GMX_ATTRIBUTE_NORETURN;
 106 /** Helper macro to pass first three parameters to gmx_fatal(). */
 107 #define FARGS 0, __FILE__, __LINE__
 108
 109 /** Sets the log file for printing error messages. */
 110 void
 111 gmx_fatal_set_log_file(FILE *fp);
 112
 113 /*! \brief
 114  * Debug log file.
 115  *
 116  * Functions can write to this file for debug info.
 117  * Before writing to it, it should be checked whether the file is not NULL:
 118  * \code
 119    if (debug)
 120    {
 121        fprintf(debug, "%s", "Debug text");
 122    }
 123    \endcode
 124  */
 125 extern FILE    *debug;
 126 /** Whether extra debugging is enabled. */
 127 extern gmx_bool gmx_debug_at;
 128
 129 /** Initializes debugging variables */
 130 void init_debug(const int dbglevel, const char *dbgfile);
 131
 132 /** Returns TRUE when the program was started in debug mode */
 133 gmx_bool bDebugMode(void);
 134
 135 /*! \brief
 136  * Implementation for range_check() and range_check_mesg().
 137  *
 138  * \p warn_str can be NULL.
 139  */
 140 void _range_check(int n, int n_min, int n_max, const char *warn_str,
 141                   const char *var,
 142                   const char *file, int line);
 143
 144 /*! \brief
 145  * Checks that a variable is within a range.
 146  *
 147  * If \p n is not in range [n_min, n_max), a fatal error is raised.
 148  * \p n_min is inclusive, but \p n_max is not.
 149  */
 150 #define range_check_mesg(n, n_min, n_max, str) _range_check(n, n_min, n_max, str,#n, __FILE__, __LINE__)
 151
 152 /*! \brief
 153  * Checks that a variable is within a range.
 154  *
 155  * This works as range_check_mesg(), but with a default error message.
 156  */
 157 #define range_check(n, n_min, n_max) _range_check(n, n_min, n_max, NULL,#n, __FILE__, __LINE__)
 158
 159 /*! \brief
 160  * Returns error message corresponding to a string key.
 161  *
 162  * This maps the strings used by gmx_error() to actual error messages.
 163  * Caller is responsible of freeing the returned string.
 164  */
 165 char *gmx_strerror(const char *key);
 166
 167 /** Implementation for gmx_error(). */
 168 void _gmx_error(const char *key, const char *msg, const char *file, int line) GMX_ATTRIBUTE_NORETURN;
 169 /*! \brief
 170  * Alternative fatal error routine with canned messages.
 171  *
 172  * This works as gmx_fatal(), except that a generic error message is added
 173  * based on a string key, and printf-style formatting is not supported.
 174  * Should not typically be called directly, but through gmx_bug(), gmx_call()
 175  * etc.
 176  */
 177 #define gmx_error(key, msg) _gmx_error(key, msg, __FILE__, __LINE__)
 178
 179 /*! \name Fatal error routines for certain types of errors
 180  *
 181  * These wrap gmx_error() and provide the \p key parameter as one of the
 182  * recognized strings.
 183  */
 184 /*! \{ */
 185 #define gmx_bug(msg)    gmx_error("bug", msg)
 186 #define gmx_call(msg)   gmx_error("call", msg)
 187 #define gmx_comm(msg)   gmx_error("comm", msg)
 188 #define gmx_file(msg)   gmx_error("file", msg)
 189 #define gmx_cmd(msg)    gmx_error("cmd", msg)
 190 #define gmx_impl(msg)   gmx_error("impl", msg)
 191 #define gmx_incons(msg) gmx_error("incons", msg)
 192 #define gmx_input(msg)  gmx_error("input", msg)
 193 #define gmx_mem(msg)    gmx_error("mem", msg)
 194 #define gmx_open(fn)    gmx_error("open", fn)
 195 /*! \} */
 196
 197 /*! \brief
 198  * Sets an error handler for gmx_fatal() and other fatal error routines.
 199  *
 200  * The default handler prints the message and aborts the program.
 201  * If you set a custom handler, it must also abort the program, otherwise
 202  * \Gromacs will behave unpredictably (most likely, it crashes shortly after
 203  * the fatal error).
 204  * The string passed to the handler may be a multi-line string.
 205  *
 206  * \see gmx_fatal()
 207  */
 208 void
 209 set_gmx_error_handler(void (*func)(const char *msg));
 210
 211 /*! \brief
 212  * Prints a warning message to stderr.
 213  *
 214  * The format of \p fmt uses printf()-like formatting.
 215  * The message string should NOT start with "WARNING"
 216  * and should NOT end with a newline.
 217  */
 218 void gmx_warning(const char *fmt, ...);
 219
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 #endif