summaryrefslogtreecommitdiffstats
path: root/doc/html/Errors.html
blob: b79c5b90168ae6c2210260d3a7f45b023410c8a1 (plain)
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
<!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>&nbsp;<br>
   <a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;<br>
   <a href="index.html">Other HDF5 documents and links</a>&nbsp;<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>&nbsp;&nbsp;&nbsp;&nbsp;
      <br>
      <a href="Files.html">Files</a>&nbsp;&nbsp;
      <a href="Datasets.html">Datasets</a>&nbsp;&nbsp;
      <a href="Datatypes.html">Datatypes</a>&nbsp;&nbsp;
      <a href="Dataspaces.html">Dataspaces</a>&nbsp;&nbsp;
      <a href="Groups.html">Groups</a>&nbsp;&nbsp;
      <br>
      <a href="References.html">References</a>&nbsp;&nbsp;
      <a href="Attributes.html">Attributes</a>&nbsp;&nbsp;
      <a href="Properties.html">Property Lists</a>&nbsp;&nbsp;
      Error Handling&nbsp;&nbsp;
      <br>
      <a href="Filters.html">Filters</a>&nbsp;&nbsp;
      <a href="Caching.html">Caching</a>&nbsp;&nbsp;
      <a href="Chunking.html">Chunking</a>&nbsp;&nbsp;
      <a href="MountingFiles.html">Mounting Files</a>&nbsp;&nbsp;
      <br>
      <a href="Performance.html">Performance</a>&nbsp;&nbsp;
      <a href="Debugging.html">Debugging</a>&nbsp;&nbsp;
      <a href="Environment.html">Environment</a>&nbsp;&nbsp;
      <a href="ddl.html">DDL</a>&nbsp;&nbsp;
</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(&amp;old_func, &amp;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-&gt;maj_num);
    min_str = H5Eget_minor (err_desc-&gt;min_num);

    /* Print error message */
    fprintf (stream, "%*s#%03d: %s line %u in %s(): %s\n",
	     indent, "", n, err_desc-&gt;file_name, err_desc-&gt;line,
	     err_desc-&gt;func_name, err_desc-&gt;desc);
    fprintf (stream, "%*smajor(%02d): %s\n",
	     indent*2, "", err_desc-&gt;maj_num, maj_str);
    fprintf (stream, "%*sminor(%02d): %s\n",
	     indent*2, "", err_desc-&gt;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>&nbsp;<br>
   <a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;<br>
   <a href="index.html">Other HDF5 documents and links</a>&nbsp;<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>&nbsp;&nbsp;&nbsp;&nbsp;
      <br>
      <a href="Files.html">Files</a>&nbsp;&nbsp;
      <a href="Datasets.html">Datasets</a>&nbsp;&nbsp;
      <a href="Datatypes.html">Datatypes</a>&nbsp;&nbsp;
      <a href="Dataspaces.html">Dataspaces</a>&nbsp;&nbsp;
      <a href="Groups.html">Groups</a>&nbsp;&nbsp;
      <br>
      <a href="References.html">References</a>&nbsp;&nbsp;
      <a href="Attributes.html">Attributes</a>&nbsp;&nbsp;
      <a href="Properties.html">Property Lists</a>&nbsp;&nbsp;
      Error Handling&nbsp;&nbsp;
      <br>
      <a href="Filters.html">Filters</a>&nbsp;&nbsp;
      <a href="Caching.html">Caching</a>&nbsp;&nbsp;
      <a href="Chunking.html">Chunking</a>&nbsp;&nbsp;
      <a href="MountingFiles.html">Mounting Files</a>&nbsp;&nbsp;
      <br>
      <a href="Performance.html">Performance</a>&nbsp;&nbsp;
      <a href="Debugging.html">Debugging</a>&nbsp;&nbsp;
      <a href="Environment.html">Environment</a>&nbsp;&nbsp;
      <a href="ddl.html">DDL</a>&nbsp;&nbsp;
</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:  13 December 1999
<!-- hhmts end -->

<br>
Describes HDF5 Release 1.4 Beta, December 2000


  </body>
</html>