3
<title>Error Handlers - GNU Scientific Library -- Reference Manual</title>
4
<meta http-equiv="Content-Type" content="text/html">
5
<meta name="description" content="GNU Scientific Library -- Reference Manual">
6
<meta name="generator" content="makeinfo 4.8">
7
<link title="Top" rel="start" href="index.html#Top">
8
<link rel="up" href="Error-Handling.html#Error-Handling" title="Error Handling">
9
<link rel="prev" href="Error-Codes.html#Error-Codes" title="Error Codes">
10
<link rel="next" href="Using-GSL-error-reporting-in-your-own-functions.html#Using-GSL-error-reporting-in-your-own-functions" title="Using GSL error reporting in your own functions">
11
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
13
Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 The GSL Team.
15
Permission is granted to copy, distribute and/or modify this document
16
under the terms of the GNU Free Documentation License, Version 1.2 or
17
any later version published by the Free Software Foundation; with the
18
Invariant Sections being ``GNU General Public License'' and ``Free Software
19
Needs Free Documentation'', the Front-Cover text being ``A GNU Manual'',
20
and with the Back-Cover Text being (a) (see below). A copy of the
21
license is included in the section entitled ``GNU Free Documentation
24
(a) The Back-Cover Text is: ``You have freedom to copy and modify this
25
GNU Manual, like GNU software.''-->
26
<meta http-equiv="Content-Style-Type" content="text/css">
27
<style type="text/css"><!--
28
pre.display { font-family:inherit }
29
pre.format { font-family:inherit }
30
pre.smalldisplay { font-family:inherit; font-size:smaller }
31
pre.smallformat { font-family:inherit; font-size:smaller }
32
pre.smallexample { font-size:smaller }
33
pre.smalllisp { font-size:smaller }
34
span.sc { font-variant:small-caps }
35
span.roman { font-family:serif; font-weight:normal; }
36
span.sansserif { font-family:sans-serif; font-weight:normal; }
42
<a name="Error-Handlers"></a>
43
Next: <a rel="next" accesskey="n" href="Using-GSL-error-reporting-in-your-own-functions.html#Using-GSL-error-reporting-in-your-own-functions">Using GSL error reporting in your own functions</a>,
44
Previous: <a rel="previous" accesskey="p" href="Error-Codes.html#Error-Codes">Error Codes</a>,
45
Up: <a rel="up" accesskey="u" href="Error-Handling.html#Error-Handling">Error Handling</a>
49
<h3 class="section">3.3 Error Handlers</h3>
51
<p><a name="index-Error-handlers-53"></a>
52
The default behavior of the GSL error handler is to print a short
53
message and call <code>abort()</code>. When this default is in use programs
54
will stop with a core-dump whenever a library routine reports an error.
55
This is intended as a fail-safe default for programs which do not check
56
the return status of library routines (we don't encourage you to write
59
<p>If you turn off the default error handler it is your responsibility to
60
check the return values of routines and handle them yourself. You can
61
also customize the error behavior by providing a new error handler. For
62
example, an alternative error handler could log all errors to a file,
63
ignore certain error conditions (such as underflows), or start the
64
debugger and attach it to the current process when an error occurs.
66
<p>All GSL error handlers have the type <code>gsl_error_handler_t</code>, which is
67
defined in <samp><span class="file">gsl_errno.h</span></samp>,
70
— Data Type: <b>gsl_error_handler_t</b><var><a name="index-gsl_005ferror_005fhandler_005ft-54"></a></var><br>
72
<p>This is the type of GSL error handler functions. An error handler will
73
be passed four arguments which specify the reason for the error (a
74
string), the name of the source file in which it occurred (also a
75
string), the line number in that file (an integer) and the error number
76
(an integer). The source file and line number are set at compile time
77
using the <code>__FILE__</code> and <code>__LINE__</code> directives in the
78
preprocessor. An error handler function returns type <code>void</code>.
79
Error handler functions should be defined like this,
81
<pre class="example"> void handler (const char * reason,
88
<p class="noindent">To request the use of your own error handler you need to call the
89
function <code>gsl_set_error_handler</code> which is also declared in
90
<samp><span class="file">gsl_errno.h</span></samp>,
93
— Function: gsl_error_handler_t * <b>gsl_set_error_handler</b> (<var>gsl_error_handler_t new_handler</var>)<var><a name="index-gsl_005fset_005ferror_005fhandler-55"></a></var><br>
95
<p>This function sets a new error handler, <var>new_handler</var>, for the GSL
96
library routines. The previous handler is returned (so that you can
97
restore it later). Note that the pointer to a user defined error
98
handler function is stored in a static variable, so there can be only
99
one error handler per program. This function should be not be used in
100
multi-threaded programs except to set up a program-wide error handler
101
from a master thread. The following example shows how to set and
102
restore a new error handler,
104
<pre class="example"> /* save original handler, install new handler */
105
old_handler = gsl_set_error_handler (&my_handler);
107
/* code uses new handler */
110
/* restore original handler */
111
gsl_set_error_handler (old_handler);
113
<p class="noindent">To use the default behavior (<code>abort</code> on error) set the error
114
handler to <code>NULL</code>,
116
<pre class="example"> old_handler = gsl_set_error_handler (NULL);
121
— Function: gsl_error_handler_t * <b>gsl_set_error_handler_off</b> ()<var><a name="index-gsl_005fset_005ferror_005fhandler_005foff-56"></a></var><br>
122
<blockquote><p>This function turns off the error handler by defining an error handler
123
which does nothing. This will cause the program to continue after any
124
error, so the return values from any library routines must be checked.
125
This is the recommended behavior for production programs. The previous
126
handler is returned (so that you can restore it later).
127
</p></blockquote></div>
129
<p>The error behavior can be changed for specific applications by
130
recompiling the library with a customized definition of the
131
<code>GSL_ERROR</code> macro in the file <samp><span class="file">gsl_errno.h</span></samp>.
added
removed
Error-Handlers.html
