File: Error-Handlers.html

package info (click to toggle)
gsl-ref-html 2.3-1
  • links: PTS
  • area: non-free
  • in suites: bullseye, buster, sid
  • size: 6,876 kB
  • ctags: 4,574
  • sloc: makefile: 35
file content (168 lines) | stat: -rw-r--r-- 8,159 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016 The GSL Team.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Free Software
Needs Free Documentation", the Front-Cover text being "A GNU Manual",
and with the Back-Cover Text being (a) (see below). A copy of the
license is included in the section entitled "GNU Free Documentation
License".

(a) The Back-Cover Text is: "You have the freedom to copy and modify this
GNU Manual." -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Scientific Library &ndash; Reference Manual: Error Handlers</title>

<meta name="description" content="GNU Scientific Library &ndash; Reference Manual: Error Handlers">
<meta name="keywords" content="GNU Scientific Library &ndash; Reference Manual: Error Handlers">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Function-Index.html#Function-Index" rel="index" title="Function Index">
<link href="Error-Handling.html#Error-Handling" rel="up" title="Error Handling">
<link href="Using-GSL-error-reporting-in-your-own-functions.html#Using-GSL-error-reporting-in-your-own-functions" rel="next" title="Using GSL error reporting in your own functions">
<link href="Error-Codes.html#Error-Codes" rel="previous" title="Error Codes">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Error-Handlers"></a>
<div class="header">
<p>
Next: <a href="Using-GSL-error-reporting-in-your-own-functions.html#Using-GSL-error-reporting-in-your-own-functions" accesskey="n" rel="next">Using GSL error reporting in your own functions</a>, Previous: <a href="Error-Codes.html#Error-Codes" accesskey="p" rel="previous">Error Codes</a>, Up: <a href="Error-Handling.html#Error-Handling" accesskey="u" rel="up">Error Handling</a> &nbsp; [<a href="Function-Index.html#Function-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Error-Handlers-1"></a>
<h3 class="section">3.3 Error Handlers</h3>
<a name="index-Error-handlers"></a>

<p>The default behavior of the GSL error handler is to print a short
message and call <code>abort</code>.  When this default is in use programs
will stop with a core-dump whenever a library routine reports an error.
This is intended as a fail-safe default for programs which do not check
the return status of library routines (we don&rsquo;t encourage you to write
programs this way).
</p>
<p>If you turn off the default error handler it is your responsibility to
check the return values of routines and handle them yourself.  You can
also customize the error behavior by providing a new error handler. For
example, an alternative error handler could log all errors to a file,
ignore certain error conditions (such as underflows), or start the
debugger and attach it to the current process when an error occurs.
</p>
<p>All GSL error handlers have the type <code>gsl_error_handler_t</code>, which is
defined in <samp>gsl_errno.h</samp>,
</p>
<dl>
<dt><a name="index-gsl_005ferror_005fhandler_005ft"></a>Data Type: <strong>gsl_error_handler_t</strong></dt>
<dd>
<p>This is the type of GSL error handler functions.  An error handler will
be passed four arguments which specify the reason for the error (a
string), the name of the source file in which it occurred (also a
string), the line number in that file (an integer) and the error number
(an integer).  The source file and line number are set at compile time
using the <code>__FILE__</code> and <code>__LINE__</code> directives in the
preprocessor.  An error handler function returns type <code>void</code>.
Error handler functions should be defined like this,
</p>
<div class="example">
<pre class="example">void handler (const char * reason, 
              const char * file, 
              int line, 
              int gsl_errno)
</pre></div>
</dd></dl>

<p>To request the use of your own error handler you need to call the
function <code>gsl_set_error_handler</code> which is also declared in
<samp>gsl_errno.h</samp>,
</p>
<dl>
<dt><a name="index-gsl_005fset_005ferror_005fhandler"></a>Function: <em>gsl_error_handler_t *</em> <strong>gsl_set_error_handler</strong> <em>(gsl_error_handler_t * <var>new_handler</var>)</em></dt>
<dd>
<p>This function sets a new error handler, <var>new_handler</var>, for the GSL
library routines.  The previous handler is returned (so that you can
restore it later).  Note that the pointer to a user defined error
handler function is stored in a static variable, so there can be only
one error handler per program.  This function should be not be used in
multi-threaded programs except to set up a program-wide error handler
from a master thread.  The following example shows how to set and
restore a new error handler,
</p>
<div class="example">
<pre class="example">/* save original handler, install new handler */
old_handler = gsl_set_error_handler (&amp;my_handler); 

/* code uses new handler */
.....     

/* restore original handler */
gsl_set_error_handler (old_handler); 
</pre></div>

<p>To use the default behavior (<code>abort</code> on error) set the error
handler to <code>NULL</code>,
</p>
<div class="example">
<pre class="example">old_handler = gsl_set_error_handler (NULL); 
</pre></div>
</dd></dl>

<dl>
<dt><a name="index-gsl_005fset_005ferror_005fhandler_005foff"></a>Function: <em>gsl_error_handler_t *</em> <strong>gsl_set_error_handler_off</strong> <em>()</em></dt>
<dd><p>This function turns off the error handler by defining an error handler
which does nothing. This will cause the program to continue after any
error, so the return values from any library routines must be checked.
This is the recommended behavior for production programs.  The previous
handler is returned (so that you can restore it later).
</p></dd></dl>

<p>The error behavior can be changed for specific applications by
recompiling the library with a customized definition of the
<code>GSL_ERROR</code> macro in the file <samp>gsl_errno.h</samp>.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Using-GSL-error-reporting-in-your-own-functions.html#Using-GSL-error-reporting-in-your-own-functions" accesskey="n" rel="next">Using GSL error reporting in your own functions</a>, Previous: <a href="Error-Codes.html#Error-Codes" accesskey="p" rel="previous">Error Codes</a>, Up: <a href="Error-Handling.html#Error-Handling" accesskey="u" rel="up">Error Handling</a> &nbsp; [<a href="Function-Index.html#Function-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>