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
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>HDF5: HDF5 Error Handling</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="hdf5doxy.css" rel="stylesheet" type="text/css">
<!-- <link href="hdf5doxy.css" rel="stylesheet" type="text/css"/>
-->
<script type="text/javascript" src="hdf5_navtree_hacks.js"></script>
</head>
<body>
<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better serve our user community by answering the following short survey: <a href="https://www.hdfgroup.org/website-survey/">https://www.hdfgroup.org/website-survey/</a></div>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="HDFG-logo.png"/></td>
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname"><a href="https://www.hdfgroup.org">HDF5</a>
 <span id="projectnumber">1.15.0.f39b228</span>
</div>
<div id="projectbrief">API Reference</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.svg"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('_h5_e__u_g.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">HDF5 Error Handling </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="sec_error"></a>
HDF5 Error Handling</h1>
<p>The HDF5 library provides an error reporting mechanism for both the library itself and for user application programs. It can trace errors through function stack and error information like file name, function name, line number, and error description.</p>
<h2><a class="anchor" id="subsec_error_intro"></a>
Introduction</h2>
<p>The HDF5 Library provides an error reporting mechanism for both the library itself and for user application programs. It can trace errors through function stack and error information like file name, function name, line number, and error description.</p>
<p><a class="el" href="_h5_e__u_g.html#subsec_error_ops">Basic Error Handling Operations</a> discusses the basic error concepts such as error stack, error record, and error message and describes the related API functions. These concepts and functions are sufficient for application programs to trace errors inside the HDF5 Library.</p>
<p><a class="el" href="_h5_e__u_g.html#subsec_error_adv">Advanced Error Handling Operations</a> talks about the advanced concepts of error class and error stack handle and talks about the related functions. With these concepts and functions, an application library or program using the HDF5 Library can have its own error report blended with HDF5's error report.</p>
<p>Starting with Release 1.8, we have a new set of Error Handling API functions. For the purpose of backward compatibility with version 1.6 and before, we still keep the old API functions, <a class="el" href="group___h5_e.html#ga7e2d223ad3bf68fe35f343b97edf0e92">H5Epush1</a>, <a class="el" href="group___h5_e.html#ga9c71eb8e5b7261668e2e8926f1822365">H5Eprint1</a>, <a class="el" href="group___h5_e.html#ga8d54a0f62f9ea625bdeab8e5e0c894c4">H5Ewalk1</a>, <a class="el" href="group___h5_e.html#ga0f2ee26cbe35c5dde49d615fc31ea2f6">H5Eclear1</a>, <a class="el" href="group___h5_e.html#ga0ca4dd7ed560882a7da176a0e2325707">H5Eget_auto1</a>, <a class="el" href="group___h5_e.html#gab7e1c2db4a0811b70227833b5462eea8">H5Eset_auto1</a>. These functions do not have the error stack as a parameter. The library allows them to operate on the default error stack. (The H5E compatibility macros will choose the correct function based on the parameters)</p>
<p>The old API is similar to functionality discussed in <a class="el" href="_h5_e__u_g.html#subsec_error_ops">Basic Error Handling Operations</a>. The functionality discussed in <a class="el" href="_h5_e__u_g.html#subsec_error_adv">Advanced Error Handling Operations</a>,the ability of allowing applications to add their own error records, is the new design for the Error Handling API.</p>
<h2><a class="anchor" id="subsec_error_H5E"></a>
Error Handling Function Summaries</h2>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group___h5_e.html">Error Handling (H5E)</a> reference manual</dd></dl>
<h2><a class="anchor" id="subsec_error_program"></a>
Programming Model for Error Handling</h2>
<p>This section is under construction.</p>
<h2><a class="anchor" id="subsec_error_ops"></a>
Basic Error Handling Operations</h2>
<p>Let us first try to understand the error stack. An error stack is a collection of error records. Error records can be pushed onto or popped off the error stack. By default, when an error occurs deep within the HDF5 Library, an error 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 API function called by the application returns a failure indication. The next API function being called will reset the error stack. All HDF5 Library error records belong to the same error class. For more information, see <a class="el" href="_h5_e__u_g.html#subsec_error_adv">Advanced Error Handling Operations</a>.</p>
<h3><a class="anchor" id="subsubsec_error_ops_stack"></a>
Error Stack and Error Message</h3>
<p>In normal circumstances, an error causes the stack to be printed on the standard error stream automatically. This automatic error stack is the library's default stack. For all the functions in this section, whenever an error stack ID is needed as a parameter, <a class="el" href="_h5_epublic_8h.html#ad7ca07d2b387a59c7e8bcab22fa57455">H5E_DEFAULT</a> can be used to indicate the library's default stack. The first error record of the error stack, number #000, is produced by the API function itself and is usually sufficient to indicate to the application what went wrong. </p><table class="doxtable">
<caption align="top">Example: An Error Message</caption>
<tr>
<td><p class="starttd"></p>
<p class="intertd">If an application calls <a class="el" href="group___h5_t.html#gafcba4db244f6a4d71e99c6e72b8678f0">H5Tclose</a> 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>
<p class="endtd"><code></p><pre>
HDF5-DIAG: Error detected in HDF5 (1.10.9) thread 0.
#000: H5T.c line ### in <a class="el" href="group___h5_t.html#gafcba4db244f6a4d71e99c6e72b8678f0" title="Releases a datatype.">H5Tclose()</a>: predefined datatype
major: Function argument
minor: Bad value
</pre><p></code> </p>
</td></tr>
</table>
<p>In the example above, we can see that an error record has a major message and a minor message. A major message generally indicates where the error happens. The location can be a dataset or a dataspace, for example. A minor message explains further details of the error. An example is “unable to open file”. Another specific detail about the error can be found at the end of the first line of each error record. This error description is usually added by the library designer to tell what exactly goes wrong. In the example above, the “predefined datatype” is an error description.</p>
<h3><a class="anchor" id="subsubsec_error_ops_print"></a>
Print and Clear an Error Stack</h3>
<p>Besides the automatic error report, the error stack can also be printed and cleared by the functions <a class="el" href="group___h5_e.html#gae86ab32e85028412c731cf0f2b8d1f56">H5Eprint2</a> and <a class="el" href="group___h5_e.html#gac9d90679c7879f3c4ebce858aaa9dfb2">H5Eclear2</a>. If an application wishes to make explicit calls to <a class="el" href="group___h5_e.html#gae86ab32e85028412c731cf0f2b8d1f56">H5Eprint2</a> to print the error stack, the automatic printing should be turned off to prevent error messages from being displayed twice (see <a class="el" href="group___h5_e.html#gaf0d6b18cd5160517fe5165b9a8443c69">H5Eset_auto2</a>).</p>
<p><em>To print an error stack:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code" href="group___h5_e.html#gae86ab32e85028412c731cf0f2b8d1f56">H5Eprint2</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> error_stack, FILE * stream)</div>
<div class="ttc" id="a_h5_ipublic_8h_html_a0045db7ff9c22ad35db6ae91662e1943"><div class="ttname"><a href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a></div><div class="ttdeci">int64_t hid_t</div><div class="ttdef"><b>Definition:</b> H5Ipublic.h:60</div></div>
<div class="ttc" id="a_h5public_8h_html_a3b079ecf932a5c599499cf7e298af160"><div class="ttname"><a href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a></div><div class="ttdeci">int herr_t</div><div class="ttdef"><b>Definition:</b> H5public.h:235</div></div>
<div class="ttc" id="agroup___h5_e_html_gae86ab32e85028412c731cf0f2b8d1f56"><div class="ttname"><a href="group___h5_e.html#gae86ab32e85028412c731cf0f2b8d1f56">H5Eprint2</a></div><div class="ttdeci">herr_t H5Eprint2(hid_t err_stack, FILE *stream)</div><div class="ttdoc">Prints the specified error stack in a default manner.</div></div>
</div><!-- fragment --><p> This function prints the error stack specified by error_stack on the specified stream, stream. If the error stack is empty, a one‐line message will be printed. The following is an example of such a message. This message would be generated if the error was in the HDF5 Library. </p><div class="fragment"><div class="line">HDF5-DIAG: Error detected in HDF5 Library version: 1.10.9 thread 0.</div>
</div><!-- fragment --><p><em>To clear an error stack:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code" href="group___h5_e.html#gac9d90679c7879f3c4ebce858aaa9dfb2">H5Eclear2</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> error_stack)</div>
<div class="ttc" id="agroup___h5_e_html_gac9d90679c7879f3c4ebce858aaa9dfb2"><div class="ttname"><a href="group___h5_e.html#gac9d90679c7879f3c4ebce858aaa9dfb2">H5Eclear2</a></div><div class="ttdeci">herr_t H5Eclear2(hid_t err_stack)</div><div class="ttdoc">Clears the specified error stack or the error stack for the current thread.</div></div>
</div><!-- fragment --><p> The <a class="el" href="group___h5_e.html#gac9d90679c7879f3c4ebce858aaa9dfb2">H5Eclear2</a> function shown above clears the error stack specified by error_stack. <a class="el" href="_h5_epublic_8h.html#ad7ca07d2b387a59c7e8bcab22fa57455">H5E_DEFAULT</a> can be passed in to clear the current error stack. The current stack is also cleared whenever an API function is called; there are certain exceptions to this rule such as <a class="el" href="group___h5_e.html#gae86ab32e85028412c731cf0f2b8d1f56">H5Eprint2</a>.</p>
<h3><a class="anchor" id="subsubsec_error_ops_mute"></a>
Mute Error Stack</h3>
<p>Sometimes an application calls a function for the sake of its return value, fully expecting the function to fail; sometimes the application wants to call <a class="el" href="group___h5_e.html#gae86ab32e85028412c731cf0f2b8d1f56">H5Eprint2</a> explicitly. In these situations, it would be misleading if an error message were still automatically printed. Using the <a class="el" href="group___h5_e.html#gaf0d6b18cd5160517fe5165b9a8443c69">H5Eset_auto2</a> function can control the automatic printing of error messages.</p>
<p><em>To enable or disable automatic printing of errors:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code" href="group___h5_e.html#gaf0d6b18cd5160517fe5165b9a8443c69">H5Eset_auto2</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> error_stack, <a class="code" href="_h5version_8h.html#a553d5a9d3baca989e9cc00d369810051">H5E_auto_t</a> func, <span class="keywordtype">void</span> *client_data)</div>
<div class="ttc" id="a_h5version_8h_html_a553d5a9d3baca989e9cc00d369810051"><div class="ttname"><a href="_h5version_8h.html#a553d5a9d3baca989e9cc00d369810051">H5E_auto_t</a></div><div class="ttdeci">#define H5E_auto_t</div><div class="ttdef"><b>Definition:</b> H5version.h:1298</div></div>
<div class="ttc" id="agroup___h5_e_html_gaf0d6b18cd5160517fe5165b9a8443c69"><div class="ttname"><a href="group___h5_e.html#gaf0d6b18cd5160517fe5165b9a8443c69">H5Eset_auto2</a></div><div class="ttdeci">herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data)</div><div class="ttdoc">Turns automatic error printing on or off.</div></div>
</div><!-- fragment --><p> The <a class="el" href="group___h5_e.html#gaf0d6b18cd5160517fe5165b9a8443c69">H5Eset_auto2</a> function can be used to turn on or off the automatic printing of errors for the error stack specified by error_stack. When turned on (non‐null func pointer), any API function which returns an error indication will first call func, passing it client_data as an argument. When the library is first initialized the auto printing function is set to <a class="el" href="group___h5_e.html#gae86ab32e85028412c731cf0f2b8d1f56">H5Eprint2</a> and client_data is the standard error stream pointer, stderr.</p>
<p><em>To see the current settings:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code" href="group___h5_e.html#gaa088620ef0b6c4ac2abcf57d61c8cdb8">H5Eget_auto</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> error_stack, <a class="code" href="_h5version_8h.html#a553d5a9d3baca989e9cc00d369810051">H5E_auto_t</a> * func, <span class="keywordtype">void</span> **client_data)</div>
<div class="ttc" id="agroup___h5_e_html_gaa088620ef0b6c4ac2abcf57d61c8cdb8"><div class="ttname"><a href="group___h5_e.html#gaa088620ef0b6c4ac2abcf57d61c8cdb8">H5Eget_auto</a></div><div class="ttdeci">#define H5Eget_auto</div><div class="ttdef"><b>Definition:</b> H5version.h:925</div></div>
</div><!-- fragment --><p> The function above returns the current settings for the automatic error stack traversal function, func, and its data, client_data. If either or both of the arguments are null, then the value is not returned.</p>
<p>An application can temporarily turn off error messages while “probing” a function. See the example below.</p>
<p><em>Example: Turn off error messages while probing a function</em> </p><div class="fragment"><div class="line">*** Save old error handler ***</div>
<div class="line"> <a class="code" href="_h5_epublic_8h.html#a0109c84ac574ac24abe6f7c7acab3fca">H5E_auto2_t</a> oldfunc;</div>
<div class="line"> <span class="keywordtype">void</span> *old_client_data;</div>
<div class="line"> <a class="code" href="group___h5_e.html#ga2eda33cbadd9be5bfddbaa91e863c936">H5Eget_auto2</a>(error_stack, &old_func, &old_client_data);</div>
<div class="line"> *** Turn off error handling ***</div>
<div class="line"> <a class="code" href="group___h5_e.html#gaf0d6b18cd5160517fe5165b9a8443c69">H5Eset_auto2</a>(error_stack, NULL, NULL);</div>
<div class="line"> *** Probe. Likely to fail, but that<span class="stringliteral">'s okay ***</span></div>
<div class="line"><span class="stringliteral"> status = H5Fopen (......);</span></div>
<div class="line"><span class="stringliteral"> *** Restore previous error handler ***</span></div>
<div class="line"><span class="stringliteral"> H5Eset_auto2(error_stack, old_func, old_client_data);</span></div>
<div class="ttc" id="a_h5_epublic_8h_html_a0109c84ac574ac24abe6f7c7acab3fca"><div class="ttname"><a href="_h5_epublic_8h.html#a0109c84ac574ac24abe6f7c7acab3fca">H5E_auto2_t</a></div><div class="ttdeci">herr_t(* H5E_auto2_t)(hid_t estack, void *client_data)</div><div class="ttdoc">Callback function for H5Eset_auto2()</div><div class="ttdef"><b>Definition:</b> H5Epublic.h:192</div></div>
<div class="ttc" id="agroup___h5_e_html_ga2eda33cbadd9be5bfddbaa91e863c936"><div class="ttname"><a href="group___h5_e.html#ga2eda33cbadd9be5bfddbaa91e863c936">H5Eget_auto2</a></div><div class="ttdeci">herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data)</div><div class="ttdoc">Returns the settings for the automatic error stack traversal function and its data.</div></div>
</div><!-- fragment --><p>Or automatic printing can be disabled altogether and error messages can be explicitly printed.</p>
<p><em>Example: Disable automatic printing and explicitly print error messages</em> </p><div class="fragment"><div class="line">*** Turn off error handling permanently ***</div>
<div class="line"><a class="code" href="group___h5_e.html#gaf0d6b18cd5160517fe5165b9a8443c69">H5Eset_auto2</a>(error_stack, NULL, NULL);</div>
<div class="line">*** If failure, print error message ***</div>
<div class="line"><span class="keywordflow">if</span> (<a class="code" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc">H5Fopen</a> (....)<0) {</div>
<div class="line"> <a class="code" href="group___h5_e.html#gae86ab32e85028412c731cf0f2b8d1f56">H5Eprint2</a>(<a class="code" href="_h5_epublic_8h.html#ad7ca07d2b387a59c7e8bcab22fa57455">H5E_DEFAULT</a>, stderr);</div>
<div class="line"> exit (1);</div>
<div class="line">}</div>
<div class="ttc" id="a_h5_epublic_8h_html_ad7ca07d2b387a59c7e8bcab22fa57455"><div class="ttname"><a href="_h5_epublic_8h.html#ad7ca07d2b387a59c7e8bcab22fa57455">H5E_DEFAULT</a></div><div class="ttdeci">#define H5E_DEFAULT</div><div class="ttdef"><b>Definition:</b> H5Epublic.h:25</div></div>
<div class="ttc" id="agroup___h5_f_html_gaa3f4f877b9bb591f3880423ed2bf44bc"><div class="ttname"><a href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc">H5Fopen</a></div><div class="ttdeci">hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id)</div><div class="ttdoc">Opens an existing HDF5 file.</div></div>
</div><!-- fragment --><h3><a class="anchor" id="subsubsec_error_ops_custom_print"></a>
Customized Printing of an Error Stack</h3>
<p>Applications are allowed to define an automatic error traversal function other than the default <a class="el" href="group___h5_e.html#gaa7e93cb96b399e5853721258872435a8">H5Eprint()</a>. For instance, one can define a function that prints a simple, one‐line error message to the standard error stream and then exits. The first example below defines a such a function. The second example below installs the function as the error handler.</p>
<p><em>Example: Defining a function to print a simple error message</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a></div>
<div class="line">my_hdf5_error_handler(<span class="keywordtype">void</span> *unused)</div>
<div class="line">{</div>
<div class="line"> fprintf (stderr, “An HDF5 error was detected. Bye.\\n”);</div>
<div class="line"> exit (1);</div>
<div class="line">}</div>
</div><!-- fragment --><p><em>Example: The user‐defined error handler</em> </p><div class="fragment"><div class="line"><a class="code" href="group___h5_e.html#gaf0d6b18cd5160517fe5165b9a8443c69">H5Eset_auto2</a>(<a class="code" href="_h5_epublic_8h.html#ad7ca07d2b387a59c7e8bcab22fa57455">H5E_DEFAULT</a>, my_hdf5_error_handler, NULL);</div>
</div><!-- fragment --><h3><a class="anchor" id="subsubsec_error_ops_walk"></a>
Walk through the Error Stack</h3>
<p>The <a class="el" href="group___h5_e.html#gae86ab32e85028412c731cf0f2b8d1f56">H5Eprint2</a> function is actually just a wrapper around the more complex <a class="el" href="group___h5_e.html#ga565cd6c7b7a197f8954d821419aba0d0">H5Ewalk</a> function which traverses an error stack and calls a user‐defined function for each member of the stack. The example below shows how <a class="el" href="group___h5_e.html#ga565cd6c7b7a197f8954d821419aba0d0">H5Ewalk</a> is used. </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code" href="group___h5_e.html#ga565cd6c7b7a197f8954d821419aba0d0">H5Ewalk</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> err_stack, <a class="code" href="_h5_epublic_8h.html#ae30cff307b364e94ce2d552edbca6813">H5E_direction_t</a> direction,</div>
<div class="line"><a class="code" href="_h5version_8h.html#a7bbdcafe87980d81a22ae5226f85c84e">H5E_walk_t</a> func, <span class="keywordtype">void</span> *client_data)</div>
<div class="ttc" id="a_h5_epublic_8h_html_ae30cff307b364e94ce2d552edbca6813"><div class="ttname"><a href="_h5_epublic_8h.html#ae30cff307b364e94ce2d552edbca6813">H5E_direction_t</a></div><div class="ttdeci">H5E_direction_t</div><div class="ttdef"><b>Definition:</b> H5Epublic.h:160</div></div>
<div class="ttc" id="a_h5version_8h_html_a7bbdcafe87980d81a22ae5226f85c84e"><div class="ttname"><a href="_h5version_8h.html#a7bbdcafe87980d81a22ae5226f85c84e">H5E_walk_t</a></div><div class="ttdeci">#define H5E_walk_t</div><div class="ttdef"><b>Definition:</b> H5version.h:971</div></div>
<div class="ttc" id="agroup___h5_e_html_ga565cd6c7b7a197f8954d821419aba0d0"><div class="ttname"><a href="group___h5_e.html#ga565cd6c7b7a197f8954d821419aba0d0">H5Ewalk</a></div><div class="ttdeci">#define H5Ewalk</div><div class="ttdef"><b>Definition:</b> H5version.h:969</div></div>
</div><!-- fragment --><p> The error stack err_stack is traversed and func is called for each member of the stack. Its arguments are an integer sequence number beginning at zero (regardless of direction) and the client_data pointer. If direction is <a class="el" href="_h5_epublic_8h.html#ae30cff307b364e94ce2d552edbca6813abedac175e65559c32551f132a78e1861">H5E_WALK_UPWARD</a>, then traversal begins at the inner‐most function that detected the error and concludes with the API function. Use <a class="el" href="_h5_epublic_8h.html#ae30cff307b364e94ce2d552edbca6813ab0ba668f408b6c98dade64021973fb49">H5E_WALK_DOWNWARD</a> for the opposite order.</p>
<h3><a class="anchor" id="subsubsec_error_ops_travers"></a>
Traverse an Error Stack with a Callback Function</h3>
<p>An error stack traversal callback function takes three arguments: n is a sequence number beginning at zero for each traversal, eptr is a pointer to an error stack member, and client_data is the same pointer used in the example above passed to <a class="el" href="group___h5_e.html#ga565cd6c7b7a197f8954d821419aba0d0">H5Ewalk</a>. See the example below. </p><div class="fragment"><div class="line"><span class="keyword">typedef</span> <a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> (*<a class="code" href="_h5version_8h.html#a7bbdcafe87980d81a22ae5226f85c84e">H5E_walk_t</a>)(<span class="keywordtype">unsigned</span> n, <a class="code" href="struct_h5_e__error2__t.html">H5E_error2_t</a> *eptr, <span class="keywordtype">void</span> *client_data)</div>
<div class="ttc" id="astruct_h5_e__error2__t_html"><div class="ttname"><a href="struct_h5_e__error2__t.html">H5E_error2_t</a></div><div class="ttdef"><b>Definition:</b> H5Epublic.h:35</div></div>
</div><!-- fragment --><p> The <a class="el" href="struct_h5_e__error2__t.html">H5E_error2_t</a> structure is shown below. </p><div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span>{</div>
<div class="line"> <a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> cls_id;</div>
<div class="line"> <a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> maj_num;</div>
<div class="line"> <a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> min_num;</div>
<div class="line"> <span class="keywordtype">unsigned</span> line;</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *func_name;</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *file_name;</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *desc;</div>
<div class="line">} <a class="code" href="struct_h5_e__error2__t.html">H5E_error2_t</a>;</div>
</div><!-- fragment --><p> The maj_num and min_num are major and minor error IDs, func_name is the name of the function where the error was detected, file_name and line locate the error within the HDF5 Library source code, and desc points to a description of the error.</p>
<p>The following example shows a user‐defined callback function.</p>
<p><em>Example: A user‐defined callback function</em> </p><div class="fragment"><div class="line">\#define MSG_SIZE 64</div>
<div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a></div>
<div class="line">custom_print_cb(<span class="keywordtype">unsigned</span> n, <span class="keyword">const</span> <a class="code" href="struct_h5_e__error2__t.html">H5E_error2_t</a> *err_desc, <span class="keywordtype">void</span> *client_data)</div>
<div class="line">{</div>
<div class="line"> FILE *stream = (FILE *)client_data;</div>
<div class="line"> <span class="keywordtype">char</span> maj[MSG_SIZE];</div>
<div class="line"> <span class="keywordtype">char</span> min[MSG_SIZE];</div>
<div class="line"> <span class="keywordtype">char</span> cls[MSG_SIZE];</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">int</span> indent = 4;</div>
<div class="line"> </div>
<div class="line"> *** Get descriptions <span class="keywordflow">for</span> the major and minor error numbers ***</div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="group___h5_e.html#gaf360b8e61728b421ee78438e4f57a001">H5Eget_class_name</a>(err_desc-><a class="code" href="struct_h5_e__error2__t.html#aeec7f232ca3cf2df54f166d02bd4a1ab">cls_id</a>, cls, MSG_SIZE) < 0)</div>
<div class="line"> TEST_ERROR;</div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="group___h5_e.html#ga64714effca13c23c4f95529256621fa0">H5Eget_msg</a>(err_desc-><a class="code" href="struct_h5_e__error2__t.html#a3602dbcfe9ecf12271a04ae00de5a41d">maj_num</a>, NULL, maj, MSG_SIZE) < 0)</div>
<div class="line"> TEST_ERROR;</div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="group___h5_e.html#ga64714effca13c23c4f95529256621fa0">H5Eget_msg</a>(err_desc-><a class="code" href="struct_h5_e__error2__t.html#ab6bbaef82664e5deee0fb3c303a14bf6">min_num</a>, NULL, min, MSG_SIZE) < 0)</div>
<div class="line"> TEST_ERROR;</div>
<div class="line"> fprintf (stream, “%*serror #%03d: %s in %s():</div>
<div class="line"> line %u\\n”,</div>
<div class="line"> indent, “”, n, err_desc-><a class="code" href="struct_h5_e__error2__t.html#a89e7a505203c95130b3355a263a38fe2">file_name</a>,</div>
<div class="line"> err_desc-><a class="code" href="struct_h5_e__error2__t.html#a0ec1958bc64e47b7629ce65b76414ce0">func_name</a>, err_desc-><a class="code" href="struct_h5_e__error2__t.html#a05ef0c4dbeec4fc8ccb225de9c26d896">line</a>);</div>
<div class="line"> fprintf (stream, “%*sclass: %s\\n”, indent*2, “”, cls);</div>
<div class="line"> fprintf (stream, “%*smajor: %s\\n”, indent*2, “”, maj);</div>
<div class="line"> fprintf (stream, “%*sminor: %s\\n”, indent*2, “”, min);</div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">error:</div>
<div class="line"> <span class="keywordflow">return</span> -1;</div>
<div class="line">}</div>
<div class="ttc" id="agroup___h5_e_html_ga64714effca13c23c4f95529256621fa0"><div class="ttname"><a href="group___h5_e.html#ga64714effca13c23c4f95529256621fa0">H5Eget_msg</a></div><div class="ttdeci">ssize_t H5Eget_msg(hid_t msg_id, H5E_type_t *type, char *msg, size_t size)</div><div class="ttdoc">Retrieves an error message.</div></div>
<div class="ttc" id="agroup___h5_e_html_gaf360b8e61728b421ee78438e4f57a001"><div class="ttname"><a href="group___h5_e.html#gaf360b8e61728b421ee78438e4f57a001">H5Eget_class_name</a></div><div class="ttdeci">ssize_t H5Eget_class_name(hid_t class_id, char *name, size_t size)</div><div class="ttdoc">Retrieves error class name.</div></div>
<div class="ttc" id="astruct_h5_e__error2__t_html_a05ef0c4dbeec4fc8ccb225de9c26d896"><div class="ttname"><a href="struct_h5_e__error2__t.html#a05ef0c4dbeec4fc8ccb225de9c26d896">H5E_error2_t::line</a></div><div class="ttdeci">unsigned line</div><div class="ttdef"><b>Definition:</b> H5Epublic.h:42</div></div>
<div class="ttc" id="astruct_h5_e__error2__t_html_a0ec1958bc64e47b7629ce65b76414ce0"><div class="ttname"><a href="struct_h5_e__error2__t.html#a0ec1958bc64e47b7629ce65b76414ce0">H5E_error2_t::func_name</a></div><div class="ttdeci">const char * func_name</div><div class="ttdef"><b>Definition:</b> H5Epublic.h:44</div></div>
<div class="ttc" id="astruct_h5_e__error2__t_html_a3602dbcfe9ecf12271a04ae00de5a41d"><div class="ttname"><a href="struct_h5_e__error2__t.html#a3602dbcfe9ecf12271a04ae00de5a41d">H5E_error2_t::maj_num</a></div><div class="ttdeci">hid_t maj_num</div><div class="ttdef"><b>Definition:</b> H5Epublic.h:38</div></div>
<div class="ttc" id="astruct_h5_e__error2__t_html_a89e7a505203c95130b3355a263a38fe2"><div class="ttname"><a href="struct_h5_e__error2__t.html#a89e7a505203c95130b3355a263a38fe2">H5E_error2_t::file_name</a></div><div class="ttdeci">const char * file_name</div><div class="ttdef"><b>Definition:</b> H5Epublic.h:46</div></div>
<div class="ttc" id="astruct_h5_e__error2__t_html_ab6bbaef82664e5deee0fb3c303a14bf6"><div class="ttname"><a href="struct_h5_e__error2__t.html#ab6bbaef82664e5deee0fb3c303a14bf6">H5E_error2_t::min_num</a></div><div class="ttdeci">hid_t min_num</div><div class="ttdef"><b>Definition:</b> H5Epublic.h:40</div></div>
<div class="ttc" id="astruct_h5_e__error2__t_html_aeec7f232ca3cf2df54f166d02bd4a1ab"><div class="ttname"><a href="struct_h5_e__error2__t.html#aeec7f232ca3cf2df54f166d02bd4a1ab">H5E_error2_t::cls_id</a></div><div class="ttdeci">hid_t cls_id</div><div class="ttdef"><b>Definition:</b> H5Epublic.h:36</div></div>
</div><!-- fragment --><h4>Programming Note for C++ Developers Using C Functions</h4>
<p>If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.</p>
<p>Examples of this kind of routine include callbacks such as <a class="el" href="group___l_a_p_l.html#ga8850042eed51777866d7bd0d050cfdc2">H5Pset_elink_cb</a> and <a class="el" href="group___d_x_p_l.html#ga10a80b29444d933da1aa2003f46cf003">H5Pset_type_conv_cb</a> and functions such as <a class="el" href="group___c_o_n_v.html#ga9442478475a03357ee47fa035df0228a">H5Tconvert</a> and <a class="el" href="group___h5_e.html#ga4ecc0f6a1ea5bb821373a5a7b8070655">H5Ewalk2</a>.</p>
<p>Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.</p>
<h2><a class="anchor" id="subsec_error_adv"></a>
Advanced Error Handling Operations</h2>
<p>The section above, see <a class="el" href="_h5_e__u_g.html#subsec_error_ops">Basic Error Handling Operations</a>, discusses the basic error handling operations of the library. In that section, all the error records on the error stack are from the library itself. In this section, we are going to introduce the operations that allow an application program to push its own error records onto the error stack once it declares an error class of its own through the HDF5 Error API.</p>
<table class="doxtable">
<caption align="top">Example: An Error Report</caption>
<tr>
<td><p class="starttd"></p>
<p class="intertd">An error report shows both the library's error record and the application's error records. See the example below. </p>
<p class="endtd"><code></p><pre>
Error Test-DIAG: Error detected in Error Program (1.0)
thread 8192:
#000: ../../hdf5/test/error_test.c line ### in main():
Error test failed
major: Error in test
minor: Error in subroutine
#001: ../../hdf5/test/error_test.c line ### in
test_error(): H5Dwrite failed as supposed to
major: Error in IO
minor: Error in H5Dwrite
HDF5-DIAG: Error detected in HDF5 (1.10.9) thread #####:
#002: ../../hdf5/src/H5Dio.c line ### in <a class="el" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906" title="Writes raw data from a buffer to a dataset.">H5Dwrite()</a>:
not a dataset
major: Invalid arguments to routine
minor: Inappropriate type
</pre><p></code> </p>
</td></tr>
</table>
<p>In the line above error record #002 in the example above, the starting phrase is HDF5. This is the error class name of the HDF5 Library. All of the library's error messages (major and minor) are in this default error class. The Error Test in the beginning of the line above error record #000 is the name of the application's error class. The first two error records, #000 and #001, are from application's error class. By definition, an error class is a group of major and minor error messages for a library (the HDF5 Library or an application library built on top of the HDF5 Library) or an application program. The error class can be registered for a library or program through the HDF5 Error API. Major and minor messages can be defined in an error class. An application will have object handles for the error class and for major and minor messages for further operation. See the example below.</p>
<p><em>Example: The user‐defined error handler</em> </p><div class="fragment"><div class="line">\#define MSG_SIZE 64</div>
<div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a></div>
<div class="line">custom_print_cb(<span class="keywordtype">unsigned</span> n, <span class="keyword">const</span> <a class="code" href="struct_h5_e__error2__t.html">H5E_error2_t</a> *err_desc,</div>
<div class="line"><span class="keywordtype">void</span>* client_data)</div>
<div class="line">{</div>
<div class="line"> FILE *stream = (FILE *)client_data;</div>
<div class="line"> <span class="keywordtype">char</span> maj[MSG_SIZE];</div>
<div class="line"> <span class="keywordtype">char</span> min[MSG_SIZE];</div>
<div class="line"> <span class="keywordtype">char</span> cls[MSG_SIZE];</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">int</span> indent = 4;</div>
<div class="line"> </div>
<div class="line"> *** Get descriptions <span class="keywordflow">for</span> the major and minor error numbers ***</div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="group___h5_e.html#gaf360b8e61728b421ee78438e4f57a001">H5Eget_class_name</a>(err_desc-><a class="code" href="struct_h5_e__error2__t.html#aeec7f232ca3cf2df54f166d02bd4a1ab">cls_id</a>, cls, MSG_SIZE) < 0)</div>
<div class="line"> TEST_ERROR;</div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="group___h5_e.html#ga64714effca13c23c4f95529256621fa0">H5Eget_msg</a>(err_desc-><a class="code" href="struct_h5_e__error2__t.html#a3602dbcfe9ecf12271a04ae00de5a41d">maj_num</a>, NULL, maj, MSG_SIZE) < 0)</div>
<div class="line"> TEST_ERROR;</div>
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="group___h5_e.html#ga64714effca13c23c4f95529256621fa0">H5Eget_msg</a>(err_desc-><a class="code" href="struct_h5_e__error2__t.html#ab6bbaef82664e5deee0fb3c303a14bf6">min_num</a>, NULL, min, MSG_SIZE) < 0)</div>
<div class="line"> TEST_ERROR;</div>
<div class="line"> fprintf (stream, “%*serror #%03d: %s in %s():</div>
<div class="line"> line %u\\n”,</div>
<div class="line"> indent, “”, n, err_desc-><a class="code" href="struct_h5_e__error2__t.html#a89e7a505203c95130b3355a263a38fe2">file_name</a>,</div>
<div class="line"> err_desc-><a class="code" href="struct_h5_e__error2__t.html#a0ec1958bc64e47b7629ce65b76414ce0">func_name</a>, err_desc-><a class="code" href="struct_h5_e__error2__t.html#a05ef0c4dbeec4fc8ccb225de9c26d896">line</a>);</div>
<div class="line"> fprintf (stream, “%*sclass: %s\\n”, indent*2, “”, cls);</div>
<div class="line"> fprintf (stream, “%*smajor: %s\\n”, indent*2, “”, maj);</div>
<div class="line"> fprintf (stream, “%*sminor: %s\\n”, indent*2, “”, min);</div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">error:</div>
<div class="line"> <span class="keywordflow">return</span> -1;</div>
<div class="line">}</div>
</div><!-- fragment --><h3><a class="anchor" id="subsubsec_error_adv_more"></a>
More Error API Functions</h3>
<p>The Error API has functions that can be used to register or unregister an error class, to create or close error messages, and to query an error class or error message. These functions are illustrated below.</p>
<p><em>To register an error class:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> <a class="code" href="group___h5_e.html#ga70ecfb35ab871ddb1cd2dfa0ac5f740c">H5Eregister_class</a>(<span class="keyword">const</span> <span class="keywordtype">char</span>* cls_name, <span class="keyword">const</span> <span class="keywordtype">char</span>* lib_name, <span class="keyword">const</span> <span class="keywordtype">char</span>* version)</div>
<div class="ttc" id="agroup___h5_e_html_ga70ecfb35ab871ddb1cd2dfa0ac5f740c"><div class="ttname"><a href="group___h5_e.html#ga70ecfb35ab871ddb1cd2dfa0ac5f740c">H5Eregister_class</a></div><div class="ttdeci">hid_t H5Eregister_class(const char *cls_name, const char *lib_name, const char *version)</div><div class="ttdoc">Registers a client library or application program to the HDF5 error API.</div></div>
</div><!-- fragment --><p> This function registers an error class with the HDF5 Library so that the application library or program can report errors together with the HDF5 Library.</p>
<p><em>To add an error message to an error class:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> <a class="code" href="group___h5_e.html#ga99a705d98873dcdd1bb6f9d5eebc5afd">H5Ecreate_msg</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> <span class="keyword">class</span>, <a class="code" href="_h5_epublic_8h.html#a415162f1ce9b31241977d0a5857caa3c">H5E_type_t</a> msg_type, <span class="keyword">const</span> <span class="keywordtype">char</span>* mesg)</div>
<div class="ttc" id="a_h5_epublic_8h_html_a415162f1ce9b31241977d0a5857caa3c"><div class="ttname"><a href="_h5_epublic_8h.html#a415162f1ce9b31241977d0a5857caa3c">H5E_type_t</a></div><div class="ttdeci">H5E_type_t</div><div class="ttdef"><b>Definition:</b> H5Epublic.h:30</div></div>
<div class="ttc" id="agroup___h5_e_html_ga99a705d98873dcdd1bb6f9d5eebc5afd"><div class="ttname"><a href="group___h5_e.html#ga99a705d98873dcdd1bb6f9d5eebc5afd">H5Ecreate_msg</a></div><div class="ttdeci">hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg)</div><div class="ttdoc">Adds a major error message to an error class.</div></div>
</div><!-- fragment --><p> This function adds an error message to an error class defined by an application library or program. The error message can be either major or minor which is indicated by parameter msg_type.</p>
<p><em>To get the name of an error class:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#af629ed855824cf5955b54529adf78ad6">ssize_t</a> <a class="code" href="group___h5_e.html#gaf360b8e61728b421ee78438e4f57a001">H5Eget_class_name</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> class_id, <span class="keywordtype">char</span>* name, <span class="keywordtype">size_t</span> size)</div>
<div class="ttc" id="a_h5public_8h_html_af629ed855824cf5955b54529adf78ad6"><div class="ttname"><a href="_h5public_8h.html#af629ed855824cf5955b54529adf78ad6">ssize_t</a></div><div class="ttdeci">int ssize_t</div><div class="ttdef"><b>Definition:</b> H5public.h:279</div></div>
</div><!-- fragment --><p> This function retrieves the name of the error class specified by the class ID.</p>
<p><em>To retrieve an error message:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#af629ed855824cf5955b54529adf78ad6">ssize_t</a> <a class="code" href="group___h5_e.html#ga64714effca13c23c4f95529256621fa0">H5Eget_msg</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> mesg_id, <a class="code" href="_h5_epublic_8h.html#a415162f1ce9b31241977d0a5857caa3c">H5E_type_t</a>* mesg_type, <span class="keywordtype">char</span>* mesg, <span class="keywordtype">size_t</span> size)</div>
</div><!-- fragment --><p> This function retrieves the error message including its length and type.</p>
<p><em>To close an error message:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code" href="group___h5_e.html#ga65b660eb16b25cc008585ba8990e8b15">H5Eclose_msg</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> mesg_id)</div>
<div class="ttc" id="agroup___h5_e_html_ga65b660eb16b25cc008585ba8990e8b15"><div class="ttname"><a href="group___h5_e.html#ga65b660eb16b25cc008585ba8990e8b15">H5Eclose_msg</a></div><div class="ttdeci">herr_t H5Eclose_msg(hid_t err_id)</div><div class="ttdoc">Closes an error message.</div></div>
</div><!-- fragment --><p> This function closes an error message.</p>
<p><em>To remove an error class:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code" href="group___h5_e.html#ga0383710d3984d19d3d2006d1151b88a2">H5Eunregister_class</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> class_id)</div>
<div class="ttc" id="agroup___h5_e_html_ga0383710d3984d19d3d2006d1151b88a2"><div class="ttname"><a href="group___h5_e.html#ga0383710d3984d19d3d2006d1151b88a2">H5Eunregister_class</a></div><div class="ttdeci">herr_t H5Eunregister_class(hid_t class_id)</div><div class="ttdoc">Removes an error class.</div></div>
</div><!-- fragment --><p> This function removes an error class from the Error API.</p>
<p>The example below shows how an application creates an error class and error messages.</p>
<p><em>Example: Create an error class and error messages</em> </p><div class="fragment"><div class="line">*** Create an error <span class="keyword">class </span>***</div>
<div class="line">class_id = <a class="code" href="group___h5_e.html#ga70ecfb35ab871ddb1cd2dfa0ac5f740c">H5Eregister_class</a>(ERR_CLS_NAME, PROG_NAME, PROG_VERS);</div>
<div class="line">*** Retrieve <span class="keyword">class </span>name ***</div>
<div class="line"><a class="code" href="group___h5_e.html#gaf360b8e61728b421ee78438e4f57a001">H5Eget_class_name</a>(class_id, cls_name, cls_size);</div>
<div class="line">*** Create a major error message in the <span class="keyword">class </span>***</div>
<div class="line">maj_id = <a class="code" href="group___h5_e.html#ga99a705d98873dcdd1bb6f9d5eebc5afd">H5Ecreate_msg</a>(class_id, <a class="code" href="_h5_epublic_8h.html#a415162f1ce9b31241977d0a5857caa3cab0e1bfd4dab03f69f9a884e9079d3acc">H5E_MAJOR</a>, “... ...”);</div>
<div class="line">*** Create a minor error message in the <span class="keyword">class </span>***</div>
<div class="line">min_id = <a class="code" href="group___h5_e.html#ga99a705d98873dcdd1bb6f9d5eebc5afd">H5Ecreate_msg</a>(class_id, <a class="code" href="_h5_epublic_8h.html#a415162f1ce9b31241977d0a5857caa3caabc45a68c0f04871387677c099abb338">H5E_MINOR</a>, “... ...”);</div>
<div class="ttc" id="a_h5_epublic_8h_html_a415162f1ce9b31241977d0a5857caa3caabc45a68c0f04871387677c099abb338"><div class="ttname"><a href="_h5_epublic_8h.html#a415162f1ce9b31241977d0a5857caa3caabc45a68c0f04871387677c099abb338">H5E_MINOR</a></div><div class="ttdeci">@ H5E_MINOR</div><div class="ttdef"><b>Definition:</b> H5Epublic.h:30</div></div>
<div class="ttc" id="a_h5_epublic_8h_html_a415162f1ce9b31241977d0a5857caa3cab0e1bfd4dab03f69f9a884e9079d3acc"><div class="ttname"><a href="_h5_epublic_8h.html#a415162f1ce9b31241977d0a5857caa3cab0e1bfd4dab03f69f9a884e9079d3acc">H5E_MAJOR</a></div><div class="ttdeci">@ H5E_MAJOR</div><div class="ttdef"><b>Definition:</b> H5Epublic.h:30</div></div>
</div><!-- fragment --><p>The example below shows how an application closes error messages and unregisters the error class.</p>
<p><em>Example: Closing error messages and unregistering the error class</em> </p><div class="fragment"><div class="line"><a class="code" href="group___h5_e.html#ga65b660eb16b25cc008585ba8990e8b15">H5Eclose_msg</a>(maj_id);</div>
<div class="line"><a class="code" href="group___h5_e.html#ga65b660eb16b25cc008585ba8990e8b15">H5Eclose_msg</a>(min_id);</div>
<div class="line"><a class="code" href="group___h5_e.html#ga0383710d3984d19d3d2006d1151b88a2">H5Eunregister_class</a>(class_id);</div>
</div><!-- fragment --><h3><a class="anchor" id="subsubsec_error_adv_app"></a>
Pushing an Application Error Message onto Error Stack</h3>
<p>An application can push error records onto or pop error records off of the error stack just as the library does internally. An error stack can be registered, and an object handle can be returned to the application so that the application can manipulate a registered error stack.</p>
<p><em>To register the current stack:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> <a class="code" href="group___h5_e.html#gac66c0955a6d821a472a3a408cdc95ae6">H5Eget_current_stack</a>(<span class="keywordtype">void</span>)</div>
<div class="ttc" id="agroup___h5_e_html_gac66c0955a6d821a472a3a408cdc95ae6"><div class="ttname"><a href="group___h5_e.html#gac66c0955a6d821a472a3a408cdc95ae6">H5Eget_current_stack</a></div><div class="ttdeci">hid_t H5Eget_current_stack(void)</div><div class="ttdoc">Returns a copy of the current error stack.</div></div>
</div><!-- fragment --><p> This function registers the current error stack, returns an object handle, and clears the current error stack. An empty error stack will also be assigned an ID.</p>
<p><em>To replace the current error stack with another:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code" href="group___h5_e.html#ga155715dd456c2b62a0b567e970af3473">H5Eset_current_stack</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> error_stack)</div>
<div class="ttc" id="agroup___h5_e_html_ga155715dd456c2b62a0b567e970af3473"><div class="ttname"><a href="group___h5_e.html#ga155715dd456c2b62a0b567e970af3473">H5Eset_current_stack</a></div><div class="ttdeci">herr_t H5Eset_current_stack(hid_t err_stack_id)</div><div class="ttdoc">Replaces the current error stack.</div></div>
</div><!-- fragment --><p> This function replaces the current error stack with another error stack specified by error_stack and clears the current error stack. The object handle error_stack is closed after this function call.</p>
<p><em>To push a new error record to the error stack:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code" href="group___h5_e.html#ga4a7d9ca6b4f7bf521d29c85bbc5b7941">H5Epush</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> error_stack, <span class="keyword">const</span> <span class="keywordtype">char</span>* file, <span class="keyword">const</span> <span class="keywordtype">char</span>* func,</div>
<div class="line"> <span class="keywordtype">unsigned</span> line, <a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> cls_id, <a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> major_id, <a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> minor_id,</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span>* desc, ... )</div>
<div class="ttc" id="agroup___h5_e_html_ga4a7d9ca6b4f7bf521d29c85bbc5b7941"><div class="ttname"><a href="group___h5_e.html#ga4a7d9ca6b4f7bf521d29c85bbc5b7941">H5Epush</a></div><div class="ttdeci">#define H5Epush</div><div class="ttdef"><b>Definition:</b> H5version.h:947</div></div>
</div><!-- fragment --><p> This function pushes a new error record onto the error stack for the current thread.</p>
<p><em>To delete some error messages:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code" href="group___h5_e.html#ga818569ac92695fb1a7836c2389faa2ba">H5Epop</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> error_stack, <span class="keywordtype">size_t</span> count)</div>
<div class="ttc" id="agroup___h5_e_html_ga818569ac92695fb1a7836c2389faa2ba"><div class="ttname"><a href="group___h5_e.html#ga818569ac92695fb1a7836c2389faa2ba">H5Epop</a></div><div class="ttdeci">herr_t H5Epop(hid_t err_stack, size_t count)</div><div class="ttdoc">Deletes specified number of error messages from the error stack.</div></div>
</div><!-- fragment --><p> This function deletes some error messages from the error stack.</p>
<p><em>To retrieve the number of error records:</em> </p><div class="fragment"><div class="line"><span class="keywordtype">int</span> <a class="code" href="group___h5_e.html#ga5c42673e2059c385a95ce3c597e0756d">H5Eget_num</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> error_stack)</div>
<div class="ttc" id="agroup___h5_e_html_ga5c42673e2059c385a95ce3c597e0756d"><div class="ttname"><a href="group___h5_e.html#ga5c42673e2059c385a95ce3c597e0756d">H5Eget_num</a></div><div class="ttdeci">ssize_t H5Eget_num(hid_t error_stack_id)</div><div class="ttdoc">Retrieves the number of error messages in an error stack.</div></div>
</div><!-- fragment --><p> This function retrieves the number of error records from an error stack.</p>
<p><em>To clear the error stack:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> H5Eclear_stack(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> error_stack)</div>
</div><!-- fragment --><p> This function clears the error stack.</p>
<p><em>To close the object handle for an error stack:</em> </p><div class="fragment"><div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code" href="group___h5_e.html#ga41c2ed13fd6aac6e413fe7383b9090fa">H5Eclose_stack</a>(<a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> error_stack)</div>
<div class="ttc" id="agroup___h5_e_html_ga41c2ed13fd6aac6e413fe7383b9090fa"><div class="ttname"><a href="group___h5_e.html#ga41c2ed13fd6aac6e413fe7383b9090fa">H5Eclose_stack</a></div><div class="ttdeci">herr_t H5Eclose_stack(hid_t stack_id)</div><div class="ttdoc">Closes an error stack handle.</div></div>
</div><!-- fragment --><p> This function closes the object handle for an error stack and releases its resources.</p>
<p>The example below shows how an application pushes an error record onto the default error stack.</p>
<p><em>Example: Pushing an error message to an error stack</em> </p><div class="fragment"><div class="line">*** Make call to HDF5 I/O routine ***</div>
<div class="line"><span class="keywordflow">if</span>((dset_id=<a class="code" href="_h5version_8h.html#a7dba2e5b2045f31c0932123ffb54f7a3">H5Dopen</a>(file_id, dset_name, access_plist)) < 0)</div>
<div class="line">{</div>
<div class="line"> *** Push client error onto error stack ***</div>
<div class="line"> <a class="code" href="group___h5_e.html#ga4a7d9ca6b4f7bf521d29c85bbc5b7941">H5Epush</a>(<a class="code" href="_h5_epublic_8h.html#ad7ca07d2b387a59c7e8bcab22fa57455">H5E_DEFAULT</a>,__FILE__,FUNC,__LINE__,cls_id,</div>
<div class="line"> CLIENT_ERR_MAJ_IO,CLIENT_ERR_MINOR_OPEN, “H5Dopen failed”);</div>
<div class="line">}</div>
<div class="line">*** Indicate error occurred in <span class="keyword">function</span> ***</div>
<div class="line"><span class="keywordflow">return</span> 0;</div>
<div class="ttc" id="a_h5version_8h_html_a7dba2e5b2045f31c0932123ffb54f7a3"><div class="ttname"><a href="_h5version_8h.html#a7dba2e5b2045f31c0932123ffb54f7a3">H5Dopen</a></div><div class="ttdeci">#define H5Dopen</div><div class="ttdef"><b>Definition:</b> H5version.h:903</div></div>
</div><!-- fragment --><p>The example below shows how an application registers the current error stack and creates an object handle to avoid another HDF5 function from clearing the error stack.</p>
<p><em>Example: Registering the error stack</em> </p><div class="fragment"><div class="line"><span class="keywordflow">if</span> (<a class="code" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906">H5Dwrite</a>(dset_id, mem_type_id, mem_space_id, file_space_id, dset_xfer_plist_id, buf) < 0)</div>
<div class="line">{</div>
<div class="line"> *** Push client error onto error stack ***</div>
<div class="line"> <a class="code" href="group___h5_e.html#ga17c2790837a1c1ea7e56b65d3c00a920">H5Epush2</a>(<a class="code" href="_h5_epublic_8h.html#ad7ca07d2b387a59c7e8bcab22fa57455">H5E_DEFAULT</a>,__FILE__,FUNC,__LINE__,cls_id,</div>
<div class="line"> CLIENT_ERR_MAJ_IO,CLIENT_ERR_MINOR_HDF5,</div>
<div class="line"> “H5Dwrite failed”);</div>
<div class="line"> *** Preserve the error stack by assigning an <span class="keywordtype">object</span> handle to it ***</div>
<div class="line"> error_stack = <a class="code" href="group___h5_e.html#gac66c0955a6d821a472a3a408cdc95ae6">H5Eget_current_stack</a>();</div>
<div class="line"> *** Close dataset ***</div>
<div class="line"> <a class="code" href="group___h5_d.html#gae47c3f38db49db127faf221624c30609">H5Dclose</a>(dset_id);</div>
<div class="line"> *** Replace the current error stack with the preserved one ***</div>
<div class="line"> <a class="code" href="group___h5_e.html#ga155715dd456c2b62a0b567e970af3473">H5Eset_current_stack</a>(error_stack);</div>
<div class="line">}</div>
<div class="line"><span class="keywordflow">return</span> 0;</div>
<div class="ttc" id="agroup___h5_d_html_ga98f44998b67587662af8b0d8a0a75906"><div class="ttname"><a href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906">H5Dwrite</a></div><div class="ttdeci">herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, const void *buf)</div><div class="ttdoc">Writes raw data from a buffer to a dataset.</div></div>
<div class="ttc" id="agroup___h5_d_html_gae47c3f38db49db127faf221624c30609"><div class="ttname"><a href="group___h5_d.html#gae47c3f38db49db127faf221624c30609">H5Dclose</a></div><div class="ttdeci">herr_t H5Dclose(hid_t dset_id)</div><div class="ttdoc">Closes the specified dataset.</div></div>
<div class="ttc" id="agroup___h5_e_html_ga17c2790837a1c1ea7e56b65d3c00a920"><div class="ttname"><a href="group___h5_e.html#ga17c2790837a1c1ea7e56b65d3c00a920">H5Epush2</a></div><div class="ttdeci">herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id, hid_t maj_id, hid_t min_id, const char *msg,...)</div><div class="ttdoc">Pushes a new error record onto an error stack.</div></div>
</div><!-- fragment --><p>Previous Chapter <a class="el" href="_h5_a__u_g.html#sec_attribute">HDF5 Attributes</a> - Next Chapter <a class="el" href="_h5_p__u_g.html#sec_plist">Properties and Property Lists in HDF5</a> </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.9.1 </li>
</ul>
</div>
</body>
</html>
|
