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
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>Error Handling Interface (H5E)</title>
</head>
<body bgcolor="#FFFFFF">
<hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="H5.intro.html">Introduction to HDF5</a> <br>
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
<a href="index.html">Other HDF5 documents and links</a> <br>
<!--
<a href="Glossary.html">Glossary</a><br>
-->
</td>
<td valign=top align=right>
And in this document, the
<a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>
<br>
<a href="Files.html">Files</a>
<a href="Datasets.html">Datasets</a>
<a href="Datatypes.html">Datatypes</a>
<a href="Dataspaces.html">Dataspaces</a>
<a href="Groups.html">Groups</a>
<br>
<a href="References.html">References</a>
<a href="Attributes.html">Attributes</a>
<a href="Properties.html">Property Lists</a>
Error Handling
<br>
<a href="Filters.html">Filters</a>
<a href="Palettes.html">Palettes</a>
<a href="Caching.html">Caching</a>
<a href="Chunking.html">Chunking</a>
<a href="MountingFiles.html">Mounting Files</a>
<br>
<a href="Performance.html">Performance</a>
<a href="Debugging.html">Debugging</a>
<a href="Environment.html">Environment</a>
<a href="ddl.html">DDL</a>
<br>
<a href="Ragged.html">Ragged Arrays</a>
</td></tr>
</table>
</center>
<hr>
<h1>The Error Handling Interface (H5E)</h1>
<h2>1. Introduction</h2>
<p>When an error occurs deep within the HDF5 library a record is
pushed onto an error stack and that function returns a failure
indication. Its caller detects the failure, pushes another
record onto the stack, and returns a failure indication. This
continues until the application-called API function returns a
failure indication (a negative integer or null pointer). The
next API function which is called (with a few exceptions) resets
the stack.
<h2>2. Error Handling Operations</h2>
<p>In normal circumstances, an error causes the stack to be
printed on the standard error stream. The first item, number
"#000" is produced by the API function itself and is usually
sufficient to indicate to the application programmer what went
wrong.
<p>
<center>
<table border align=center width="100%">
<caption align=top><h4>Example: An Error Message</h4></caption>
<tr>
<td>
<p>If an application calls <code>H5Tclose</code> on a
predefined datatype then the following message is
printed on the standard error stream. This is a
simple error that has only one component, the API
function; other errors may have many components.
<p><code><pre>
HDF5-DIAG: Error detected in thread 0. Back trace follows.
#000: H5T.c line 462 in H5Tclose(): predefined datatype
major(01): Function argument
minor(05): Bad value
</code></pre>
</td>
</tr>
</table>
</center>
<p>The error stack can also be printed and manipulated by these
functions, but if an application wishes make explicit calls to
<code>H5Eprint()</code> then the automatic printing should be
turned off to prevent error messages from being displayed twice
(see <code>H5Eset_auto()</code> below).
<dl>
<dt><code>herr_t H5Eprint (FILE *<em>stream</em>)</code>
<dd>The error stack is printed on the specified stream. Even if
the error stack is empty a one-line message will be printed:
<code>HDF5-DIAG: Error detected in thread 0.</code>
<br><br>
<dt><code>herr_t H5Eclear (void)</code>
<dd>The error stack can be explicitly cleared by calling this
function. The stack is also cleared whenever an API function
is called, with certain exceptions (for instance,
<code>H5Eprint()</code>).
</dl>
<p>Sometimes an application will call a function for the sake of
its return value, fully expecting the function to fail. Under
these conditions, it would be misleading if an error message
were automatically printed. Automatic printing of messages is
controlled by the <code>H5Eset_auto()</code> function:
<dl>
<dt><code>herr_t H5Eset_auto (herr_t(*<em>func</em>)(void*),
void *<em>client_data</em>)</code>
<dd>If <em>func</em> is not a null pointer, then the function to
which it points will be called automatically when an API
function is about to return an indication of failure. The
function is called with a single argument, the
<em>client_data</em> pointer. When the library is first
initialized the auto printing function is set to
<code>H5Eprint()</code> (cast appropriately) and
<em>client_data</em> is the standard error stream pointer,
<code>stderr</code>.
<br><br>
<dt><code>herr_t H5Eget_auto (herr_t(**<em>func</em>)(void*),
void **<em>client_data</em>)</code>
<dd>This function returns the current automatic error traversal
settings through the <em>func</em> and <em>client_data</em>
arguments. Either (or both) arguments may be null pointers in
which case the corresponding information is not returned.
</dl>
<p>
<center>
<table border align=center width="100%">
<caption align=top><h4>Example: Error Control</h4></caption>
<tr>
<td>
<p>An application can temporarily turn off error
messages while "probing" a function.
<p><code><pre>
/* Save old error handler */
herr_t (*old_func)(void*);
void *old_client_data;
H5Eget_auto(&old_func, &old_client_data);
/* Turn off error handling */
H5Eset_auto(NULL, NULL);
/* Probe. Likely to fail, but that's okay */
status = H5Fopen (......);
/* Restore previous error handler */
H5Eset_auto(old_func, old_client_data);
</code></pre>
<p>Or automatic printing can be disabled altogether and
error messages can be explicitly printed.
<p><code><pre>
/* Turn off error handling permanently */
H5Eset_auto (NULL, NULL);
/* If failure, print error message */
if (H5Fopen (....)<0) {
H5Eprint (stderr);
exit (1);
}
</code></pre>
</td>
</tr>
</table>
</center>
<p>The application is allowed to define an automatic error
traversal function other than the default
<code>H5Eprint()</code>. For instance, one could define a
function that prints a simple, one-line error message to the
standard error stream and then exits.
<p>
<center>
<table border align=center width="100%">
<caption align=top><h4>Example: Simple Messages</h4></caption>
<tr>
<td>
<p>The application defines a function to print a simple
error message to the standard error stream.
<p><code><pre>
herr_t
my_hdf5_error_handler (void *unused)
{
fprintf (stderr, "An HDF5 error was detected. Bye.\n");
exit (1);
}
</code></pre>
<p>The function is installed as the error handler by
saying
<p><code><pre>
H5Eset_auto (my_hdf5_error_handler, NULL);
</code></pre>
</td>
</tr>
</table>
</center>
<p>The <code>H5Eprint()</code> function is actually just a wrapper
around the more complex <code>H5Ewalk()</code> function which
traverses an error stack and calls a user-defined function for
each member of the stack.
<dl>
<dt><code>herr_t H5Ewalk (H5E_direction_t <em>direction</em>,
H5E_walk_t <em>func</em>, void *<em>client_data</em>)</code>
<dd>The error stack is traversed and <em>func</em> is called for
each member of the stack. Its arguments are an integer
sequence number beginning at zero (regardless of
<em>direction</em>), a pointer to an error description record,
and the <em>client_data</em> pointer. If <em>direction</em>
is <code>H5E_WALK_UPWARD</code> then traversal begins at the
inner-most function that detected the error and concludes with
the API function. The opposite order is
<code>H5E_WALK_DOWNWARD</code>.
<br><br>
<dt><code>typedef herr_t (*H5E_walk_t)(int <em>n</em>,
H5E_error_t *<em>eptr</em>, void
*<em>client_data</em>)</code>
<dd>An error stack traversal callback function takes three
arguments: <em>n</em> is a sequence number beginning at zero
for each traversal, <em>eptr</em> is a pointer to an error
stack member, and <em>client_data</em> is the same pointer
passed to <code>H5Ewalk()</code>.
<br><br>
<dt><pre><code>typedef struct {
H5E_major_t <em>maj_num</em>;
H5E_minor_t <em>min_num</em>;
const char *<em>func_name</em>;
const char *<em>file_name</em>;
unsigned <em>line</em>;
const char *<em>desc</em>;
} H5E_error_t;</code></pre>
<dd>The <em>maj_num</em> and <em>min_num</em> are major
and minor error numbers, <em>func_name</em> is the name of
the function where the error was detected,
<em>file_name</em> and <em>line</em> locate the error
within the HDF5 library source code, and <em>desc</em>
points to a description of the error.
<br><br>
<dt><code>const char *H5Eget_major (H5E_major_t <em>num</em>)</code>
<dt><code>const char *H5Eget_minor (H5E_minor_t <em>num</em>)</code>
<dd>These functions take a major or minor error number and
return a constant string which describes the error. If
<em>num</em> is out of range than a string like "Invalid major
error number" is returned.
</dl>
<p>
<center>
<table border align=center width="100%">
<caption align=top><h4>Example: H5Ewalk_cb</h4></caption>
<tr>
<td>
<p>This is the implementation of the default error stack
traversal callback.
<p><code><pre>
herr_t
H5Ewalk_cb(int n, H5E_error_t *err_desc, void *client_data)
{
FILE *stream = (FILE *)client_data;
const char *maj_str = NULL;
const char *min_str = NULL;
const int indent = 2;
/* Check arguments */
assert (err_desc);
if (!client_data) client_data = stderr;
/* Get descriptions for the major and minor error numbers */
maj_str = H5Eget_major (err_desc->maj_num);
min_str = H5Eget_minor (err_desc->min_num);
/* Print error message */
fprintf (stream, "%*s#%03d: %s line %u in %s(): %s\n",
indent, "", n, err_desc->file_name, err_desc->line,
err_desc->func_name, err_desc->desc);
fprintf (stream, "%*smajor(%02d): %s\n",
indent*2, "", err_desc->maj_num, maj_str);
fprintf (stream, "%*sminor(%02d): %s\n",
indent*2, "", err_desc->min_num, min_str);
return 0;
}
</code></pre>
</td>
</tr>
</table>
</center>
<hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="H5.intro.html">Introduction to HDF5</a> <br>
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
<a href="index.html">Other HDF5 documents and links</a> <br>
<!--
<a href="Glossary.html">Glossary</a><br>
-->
</td>
<td valign=top align=right>
And in this document, the
<a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>
<br>
<a href="Files.html">Files</a>
<a href="Datasets.html">Datasets</a>
<a href="Datatypes.html">Datatypes</a>
<a href="Dataspaces.html">Dataspaces</a>
<a href="Groups.html">Groups</a>
<br>
<a href="References.html">References</a>
<a href="Attributes.html">Attributes</a>
<a href="Properties.html">Property Lists</a>
Error Handling
<br>
<a href="Filters.html">Filters</a>
<a href="Palettes.html">Palettes</a>
<a href="Caching.html">Caching</a>
<a href="Chunking.html">Chunking</a>
<a href="MountingFiles.html">Mounting Files</a>
<br>
<a href="Performance.html">Performance</a>
<a href="Debugging.html">Debugging</a>
<a href="Environment.html">Environment</a>
<a href="ddl.html">DDL</a>
<br>
<a href="Ragged.html">Ragged Arrays</a>
</td></tr>
</table>
</center>
<hr>
<address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
</address>
<!-- Created: Fri Feb 27 23:42:52 EST 1998 -->
<!-- hhmts start -->
Last modified: 14 October 1999
<!-- hhmts end -->
</body>
</html>
|
