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
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
|
<!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.10.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>HDF5: Datatype Basics</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>
<script type="text/javascript" src="cookie.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:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(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.2908dd1</span>
</div>
<div id="projectbrief">API Reference</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<span id="MSearchSelect" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"> </span>
<input type="text" id="MSearchField" value="" placeholder="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.10.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "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:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function(){initNavTree('_l_b_datatypes.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">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">Datatype Basics</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Navigate back: <a class="el" href="index.html">Main</a> / <a class="el" href="_getting_started.html">Getting Started with HDF5</a> / <a class="el" href="_learn_basics.html">Learning the Basics</a> </p><hr />
<h1><a class="anchor" id="secLBDtype"></a>
What is a Datatype?</h1>
<p>A datatype is a collection of datatype properties which provide complete information for data conversion to or from that datatype.</p>
<p>Datatypes in HDF5 can be grouped as follows: </p><ul>
<li><b>Pre-Defined Datatypes</b>: These are datatypes that are created by HDF5. They are actually opened (and closed) by HDF5, and can have a different value from one HDF5 session to the next. </li>
<li><b>Derived Datatypes</b>: These are datatypes that are created or derived from the pre-defined datatypes. Although created from pre-defined types, they represent a category unto themselves. An example of a commonly used derived datatype is a string of more than one character.</li>
</ul>
<h1><a class="anchor" id="secLBDtypePre"></a>
Pre-defined Datatypes</h1>
<p>The properties of pre-defined datatypes are: </p><ul>
<li>Pre-defined datatypes are opened and closed by HDF5. </li>
<li>A pre-defined datatype is a handle and is NOT PERSISTENT. Its value can be different from one HDF5 session to the next. </li>
<li>Pre-defined datatypes are Read-Only. </li>
<li>As mentioned, other datatypes can be derived from pre-defined datatypes.</li>
</ul>
<p>There are two types of pre-defined datatypes, standard (file) and native.</p>
<h4>Standard</h4>
<p>A standard (or file) datatype can be: </p><ul>
<li>
<b>Atomic</b>: A datatype which cannot be decomposed into smaller datatype units at the API level. The atomic datatypes are: <ul>
<li>
integer </li>
<li>
float </li>
<li>
string (1-character) </li>
<li>
date and time </li>
<li>
bitfield </li>
<li>
reference </li>
<li>
opaque </li>
</ul>
</li>
<li>
<b>Composite</b>: An aggregation of one or more datatypes. Composite datatypes include: <ul>
<li>
array </li>
<li>
variable length </li>
<li>
enumeration </li>
<li>
compound datatypes </li>
</ul>
Array, variable length, and enumeration datatypes are defined in terms of a single atomic datatype, whereas a compound datatype is a datatype composed of a sequence of datatypes. </li>
</ul>
<table class="doxtable">
<tr>
<th><b>Notes</b> </th></tr>
<tr>
<td><ul>
<li>Standard pre-defined datatypes are the SAME on all platforms. </li>
<li>They are the datatypes that you see in an HDF5 file. </li>
<li>They are typically used when creating a dataset. </li>
</ul>
</td></tr>
</table>
<h4>Native</h4>
<p>Native pre-defined datatypes are used for memory operations, such as reading and writing. They are NOT THE SAME on different platforms. They are similar to C type names, and are aliased to the appropriate HDF5 standard pre-defined datatype for a given platform.</p>
<p>For example, when on an Intel based PC, <a class="el" href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a> is aliased to the standard pre-defined type, <a class="el" href="group___p_d_t_s_t_d.html#ga8db8c9c2bcc457f9f8526c8fcb81218b">H5T_STD_I32LE</a>. On a MIPS machine, it is aliased to <a class="el" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a>. </p><table class="doxtable">
<tr>
<th><b>Notes</b> </th></tr>
<tr>
<td><ul>
<li>Native datatypes are NOT THE SAME on all platforms. </li>
<li>Native datatypes simplify memory operations (read/write). The HDF5 library automatically converts as needed. </li>
<li>Native datatypes are NOT in an HDF5 File. The standard pre-defined datatype that a native datatype corresponds to is what you will see in the file. </li>
</ul>
</td></tr>
</table>
<h4>Pre-Defined</h4>
<p>The following table shows the native types and the standard pre-defined datatypes they correspond to. (Keep in mind that HDF5 can convert between datatypes, so you can specify a buffer of a larger type for a dataset of a given type. For example, you can read a dataset that has a short datatype into a long integer buffer.)</p>
<table class="doxtable">
<caption>Some HDF5 pre-defined native datatypes and corresponding standard (file) type</caption>
<tr>
<th><b>C Type</b> </th><th><b>HDF5 Memory Type</b> </th><th><b>HDF5 File Type*</b> </th></tr>
<tr>
<th span="3"><b>Integer</b> </th></tr>
<tr>
<td>int </td><td><a class="el" href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a> </td><td><a class="el" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a> or <a class="el" href="group___p_d_t_s_t_d.html#ga8db8c9c2bcc457f9f8526c8fcb81218b">H5T_STD_I32LE</a> </td></tr>
<tr>
<td>short </td><td><a class="el" href="group___p_d_t_n_a_t.html#gae0625357fa121eca117f7fa9c4701810">H5T_NATIVE_SHORT</a> </td><td><a class="el" href="group___p_d_t_s_t_d.html#gadc0ccea703096e20a4c3e51e858836dd">H5T_STD_I16BE</a> or <a class="el" href="group___p_d_t_s_t_d.html#gaf88985315398de5fc4a716707b5c7694">H5T_STD_I16LE</a> </td></tr>
<tr>
<td>long </td><td><a class="el" href="group___p_d_t_n_a_t.html#ga290b9655882754ee0ec9f31b42ac04f6">H5T_NATIVE_LONG</a> </td><td><a class="el" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a>, <a class="el" href="group___p_d_t_s_t_d.html#ga8db8c9c2bcc457f9f8526c8fcb81218b">H5T_STD_I32LE</a>, <a class="el" href="group___p_d_t_s_t_d.html#ga7a14305593830bbe08a622642eae928c">H5T_STD_I64BE</a> or <a class="el" href="group___p_d_t_s_t_d.html#ga591a85b894eab3e3ab1a2ccd9b3be565">H5T_STD_I64LE</a> </td></tr>
<tr>
<td>long long </td><td><a class="el" href="group___p_d_t_n_a_t.html#gafb9c5d393d693869d7d21f71753a532c">H5T_NATIVE_LLONG</a> </td><td><a class="el" href="group___p_d_t_s_t_d.html#ga7a14305593830bbe08a622642eae928c">H5T_STD_I64BE</a> or <a class="el" href="group___p_d_t_s_t_d.html#ga591a85b894eab3e3ab1a2ccd9b3be565">H5T_STD_I64LE</a> </td></tr>
<tr>
<td>unsigned int </td><td><a class="el" href="group___p_d_t_n_a_t.html#ga904b507c7b8aa4838fbb7c6ce71a37c5">H5T_NATIVE_UINT</a> </td><td><a class="el" href="group___p_d_t_s_t_d.html#ga320fc4cfe8e4a3d1ab9997c8e342780b">H5T_STD_U32BE</a> or <a class="el" href="group___p_d_t_s_t_d.html#gaa03600cecf2cd9063346084e41eb82a3">H5T_STD_U32LE</a> </td></tr>
<tr>
<td>unsigned short </td><td><a class="el" href="group___p_d_t_n_a_t.html#gad0a240282e54647b83fe28ef65b40655">H5T_NATIVE_USHORT</a> </td><td><a class="el" href="group___p_d_t_s_t_d.html#ga10e46ab72ac0330c51ed6cf709db4697">H5T_STD_U16BE</a> or <a class="el" href="group___p_d_t_s_t_d.html#ga4c2494c16f3e9443af1d56a078e0db3c">H5T_STD_U16LE</a> </td></tr>
<tr>
<td>unsigned long </td><td><a class="el" href="group___p_d_t_n_a_t.html#gacaea6c2c381167bacf67f6d6c43eb718">H5T_NATIVE_ULONG</a> </td><td><a class="el" href="group___p_d_t_s_t_d.html#ga320fc4cfe8e4a3d1ab9997c8e342780b">H5T_STD_U32BE</a>, <a class="el" href="group___p_d_t_s_t_d.html#gaa03600cecf2cd9063346084e41eb82a3">H5T_STD_U32LE</a>, <a class="el" href="group___p_d_t_s_t_d.html#ga417489ff74b1cc52d25259c6357dcc6b">H5T_STD_U64BE</a> or <a class="el" href="group___p_d_t_s_t_d.html#ga3a38267be678af40576a380617e3fff9">H5T_STD_U64LE</a> </td></tr>
<tr>
<td>unsigned long long </td><td><a class="el" href="group___p_d_t_n_a_t.html#ga91ed0d2ce3289ef3707449cf5babe928">H5T_NATIVE_ULLONG</a> </td><td><a class="el" href="group___p_d_t_s_t_d.html#ga417489ff74b1cc52d25259c6357dcc6b">H5T_STD_U64BE</a> or <a class="el" href="group___p_d_t_s_t_d.html#ga3a38267be678af40576a380617e3fff9">H5T_STD_U64LE</a> </td></tr>
<tr>
<th span="3"><b>Float</b> </th></tr>
<tr>
<td>float </td><td><a class="el" href="group___p_d_t_n_a_t.html#gae2523b63144b498f555fa4d04f59ee1c">H5T_NATIVE_FLOAT</a> </td><td><a class="el" href="group___p_d_t_i_e_e_e.html#ga71d24a7d4c373ed9a003d7a0d8133f1e">H5T_IEEE_F32BE</a> or <a class="el" href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a> </td></tr>
<tr>
<td>double </td><td><a class="el" href="group___p_d_t_n_a_t.html#ga087f3b793a299e416bd68678c2ef7c09">H5T_NATIVE_DOUBLE</a> </td><td><a class="el" href="group___p_d_t_i_e_e_e.html#gaf5064f4498d92e5992a5a0564d026d35">H5T_IEEE_F64BE</a> or <a class="el" href="group___p_d_t_i_e_e_e.html#ga3f9c2185ec16632fab8c20ec7a63178e">H5T_IEEE_F64LE</a> </td></tr>
</table>
<table class="doxtable">
<caption>Some HDF5 pre-defined native datatypes and corresponding standard (file) type</caption>
<tr>
<th><b>F90 Type</b> </th><th><b>HDF5 Memory Type</b> </th><th><b>HDF5 File Type*</b> </th></tr>
<tr>
<td>integer </td><td>H5T_NATIVE_INTEGER </td><td><a class="el" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE(8,16)</a> or <a class="el" href="group___p_d_t_s_t_d.html#ga8db8c9c2bcc457f9f8526c8fcb81218b">H5T_STD_I32LE(8,16)</a> </td></tr>
<tr>
<td>real </td><td>H5T_NATIVE_REAL </td><td><a class="el" href="group___p_d_t_i_e_e_e.html#ga71d24a7d4c373ed9a003d7a0d8133f1e">H5T_IEEE_F32BE</a> or <a class="el" href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a> </td></tr>
<tr>
<td>double-precision </td><td><a class="el" href="group___p_d_t_n_a_t.html#ga087f3b793a299e416bd68678c2ef7c09">H5T_NATIVE_DOUBLE</a> </td><td><a class="el" href="group___p_d_t_i_e_e_e.html#gaf5064f4498d92e5992a5a0564d026d35">H5T_IEEE_F64BE</a> or <a class="el" href="group___p_d_t_i_e_e_e.html#ga3f9c2185ec16632fab8c20ec7a63178e">H5T_IEEE_F64LE</a> </td></tr>
</table>
<table class="doxtable">
<tr>
<td>* Note that the HDF5 File Types listed are those that are most commonly created. The file type created depends on the compiler switches and platforms being used. For example, on the Cray an integer is 64-bit, and using <a class="el" href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a> (C) or H5T_NATIVE_INTEGER (F90) would result in an <a class="el" href="group___p_d_t_s_t_d.html#ga7a14305593830bbe08a622642eae928c">H5T_STD_I64BE</a> file type. </td></tr>
</table>
<p>The following code is an example of when you would use standard pre-defined datatypes vs. native types: </p><div class="fragment"><div class="line"><span class="preprocessor">#include "hdf5.h"</span></div>
<div class="line"> </div>
<div class="line">main() {</div>
<div class="line"> </div>
<div class="line"> <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file_id, dataset_id, dataspace_id; </div>
<div class="line"> <a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> status;</div>
<div class="line"> <a class="code hl_typedef" href="_h5public_8h.html#a7f81cce70fb546af88da24d9285d3c1c">hsize_t</a> dims[2]={4,6};</div>
<div class="line"> <span class="keywordtype">int</span> i, j, dset_data[4][6];</div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">for</span> (i = 0; i < 4; i++)</div>
<div class="line"> <span class="keywordflow">for</span> (j = 0; j < 6; j++)</div>
<div class="line"> dset_data[i][j] = i * 6 + j + 1;</div>
<div class="line"> </div>
<div class="line"> file_id = <a class="code hl_function" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a> (<span class="stringliteral">"dtypes.h5"</span>, <a class="code hl_define" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a>, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>);</div>
<div class="line"> </div>
<div class="line"> dataspace_id = <a class="code hl_function" href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae">H5Screate_simple</a> (2, dims, NULL);</div>
<div class="line"> </div>
<div class="line"> dataset_id = <a class="code hl_define" href="group___h5_d.html#ga0647ba4bbd26d5230cc07f3a5685b2cf">H5Dcreate</a> (file_id, <span class="stringliteral">"/dset"</span>, <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a>, dataspace_id, </div>
<div class="line"> <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>);</div>
<div class="line"> </div>
<div class="line"> status = <a class="code hl_function" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906">H5Dwrite</a> (dataset_id, <a class="code hl_define" href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a>, <a class="code hl_define" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a>, <a class="code hl_define" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a>, </div>
<div class="line"> <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, dset_data);</div>
<div class="line"> </div>
<div class="line"> status = <a class="code hl_function" href="group___h5_d.html#gae47c3f38db49db127faf221624c30609">H5Dclose</a> (dataset_id);</div>
<div class="line"> </div>
<div class="line"> status = <a class="code hl_function" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a> (file_id);</div>
<div class="line">}</div>
<div class="ttc" id="a_h5_fpublic_8h_html_a5a2d6726f9ad8d2bca8df2b817e5ad6a"><div class="ttname"><a href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a></div><div class="ttdeci">#define H5F_ACC_TRUNC</div><div class="ttdef"><b>Definition</b> H5Fpublic.h:50</div></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_h5_ppublic_8h_html_afa85e97bfbf9bf1c58e39263846c568f"><div class="ttname"><a href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a></div><div class="ttdeci">#define H5P_DEFAULT</div><div class="ttdef"><b>Definition</b> H5Ppublic.h:102</div></div>
<div class="ttc" id="a_h5_spublic_8h_html_a5f96eeee84b987f18470737f85af0484"><div class="ttname"><a href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a></div><div class="ttdeci">#define H5S_ALL</div><div class="ttdef"><b>Definition</b> H5Spublic.h:32</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="a_h5public_8h_html_a7f81cce70fb546af88da24d9285d3c1c"><div class="ttname"><a href="_h5public_8h.html#a7f81cce70fb546af88da24d9285d3c1c">hsize_t</a></div><div class="ttdeci">uint64_t hsize_t</div><div class="ttdef"><b>Definition</b> H5public.h:297</div></div>
<div class="ttc" id="agroup___h5_d_html_ga0647ba4bbd26d5230cc07f3a5685b2cf"><div class="ttname"><a href="group___h5_d.html#ga0647ba4bbd26d5230cc07f3a5685b2cf">H5Dcreate</a></div><div class="ttdeci">#define H5Dcreate</div><div class="ttdef"><b>Definition</b> H5version.h:892</div></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_f_html_gac55cd91d80822e4f8c2a7f04ea71b124"><div class="ttname"><a href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a></div><div class="ttdeci">herr_t H5Fclose(hid_t file_id)</div><div class="ttdoc">Terminates access to an HDF5 file.</div></div>
<div class="ttc" id="agroup___h5_f_html_gae64b51ee9ac0781bc4ccc599d98387f4"><div class="ttname"><a href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a></div><div class="ttdeci">hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id)</div><div class="ttdoc">Creates an HDF5 file.</div></div>
<div class="ttc" id="agroup___h5_s_html_ga8e35eea5738b4805856eac7d595254ae"><div class="ttname"><a href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae">H5Screate_simple</a></div><div class="ttdeci">hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[])</div><div class="ttdoc">Creates a new simple dataspace and opens it for access.</div></div>
<div class="ttc" id="agroup___p_d_t_n_a_t_html_ga3cf93ffc6782be68070ef8e00f219ec2"><div class="ttname"><a href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a></div><div class="ttdeci">#define H5T_NATIVE_INT</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:767</div></div>
<div class="ttc" id="agroup___p_d_t_s_t_d_html_ga37e8a6be7ee64587c2a282b965019bb8"><div class="ttname"><a href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a></div><div class="ttdeci">#define H5T_STD_I32BE</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:305</div></div>
</div><!-- fragment --><p> By using the native types when reading and writing, the code that reads from or writes to a dataset can be the same for different platforms.</p>
<p>Can native types also be used when creating a dataset? Yes. However, just be aware that the resulting datatype in the file will be one of the standard pre-defined types and may be different than expected.</p>
<p>What happens if you do not use the correct native datatype for a standard (file) datatype? Your data may be incorrect or not what you expect.</p>
<h1><a class="anchor" id="secLBDtypeDer"></a>
Derived Datatypes</h1>
<p>ANY pre-defined datatype can be used to derive user-defined datatypes.</p>
<p>To create a datatype derived from a pre-defined type: </p><ol>
<li>
Make a copy of the pre-defined datatype: <div class="fragment"><div class="line">tid = <a class="code hl_function" href="group___h5_t.html#gaec07efbab84f4e5b4ed22f010786be8e">H5Tcopy</a> (<a class="code hl_define" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a>);</div>
<div class="ttc" id="agroup___h5_t_html_gaec07efbab84f4e5b4ed22f010786be8e"><div class="ttname"><a href="group___h5_t.html#gaec07efbab84f4e5b4ed22f010786be8e">H5Tcopy</a></div><div class="ttdeci">hid_t H5Tcopy(hid_t type_id)</div><div class="ttdoc">Copies an existing datatype.</div></div>
</div><!-- fragment --> </li>
<li>
Change the datatype. </li>
</ol>
<p>There are numerous datatype functions that allow a user to alter a pre-defined datatype. See <a class="el" href="#subsecLBDtypeSpecStr">String</a> below for a simple example.</p>
<p>Refer to the <a class="el" href="group___h5_t.html">Datatypes (H5T)</a> in the <a class="el" href="_r_m.html">HDF5 Reference Manual</a>. Example functions are <a class="el" href="group___h5_t.html#gae5f38bfd4a4c557496b3194b5180212c" title="Sets size for a datatype.">H5Tset_size</a> and <a class="el" href="group___a_t_o_m.html#gab0f4dccfc2fb47bf2c7e06c9bf84c1f7" title="Sets the precision of an atomic datatype.">H5Tset_precision</a>.</p>
<h1><a class="anchor" id="secLBDtypeSpec"></a>
Specific Datatypes</h1>
<p>On the <a class="el" href="_ex_a_p_i.html">Examples by API</a> page under <a class="el" href="_ex_a_p_i.html#sec_exapi_dtypes">Datatypes</a> you will find many example programs for creating and reading datasets with different datatypes.</p>
<p>Below is additional information on some of the datatypes. See the <a class="el" href="_ex_a_p_i.html">Examples by API</a> page for examples of these datatypes.</p>
<h2><a class="anchor" id="subsecLBDtypeSpec"></a>
Array Datatype vs Array Dataspace</h2>
<p><a class="el" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a547a4451911e912127f300ab15113854">H5T_ARRAY</a> is a datatype, and it should not be confused with the dataspace of a dataset. The dataspace of a dataset can consist of a regular array of elements. For example, the datatype for a dataset could be an atomic datatype like integer, and the dataset could be an N-dimensional appendable array, as specified by the dataspace. See <a class="el" href="group___h5_s.html#gabee514327cba34ca9951b24fa14fb083" title="Creates a new dataspace of a specified type.">H5Screate</a> and <a class="el" href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae" title="Creates a new simple dataspace and opens it for access.">H5Screate_simple</a> for details.</p>
<p>Unlimited dimensions and subsetting are not supported when using the <a class="el" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a547a4451911e912127f300ab15113854">H5T_ARRAY</a> datatype.</p>
<p>The <a class="el" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a547a4451911e912127f300ab15113854">H5T_ARRAY</a> datatype was primarily created to address the simple case of a compound datatype when all members of the compound datatype are of the same type and there is no need to subset by compound datatype members. Creation of such a datatype is more efficient and I/O also requires less work, because there is no alignment involved.</p>
<h2><a class="anchor" id="subsecLBDtypeSpecArr"></a>
Array Datatype</h2>
<p>The array class of datatypes, <a class="el" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a547a4451911e912127f300ab15113854">H5T_ARRAY</a>, allows the construction of true, homogeneous, multi-dimensional arrays. Since these are homogeneous arrays, each element of the array will be of the same datatype, designated at the time the array is created.</p>
<p>Users may be confused by this datatype, as opposed to a dataset with a simple atomic datatype (eg. integer) that is an array. See subsecLBDtypeSpec for more information.</p>
<p>Arrays can be nested. Not only is an array datatype used as an element of an HDF5 dataset, but the elements of an array datatype may be of any datatype, including another array datatype.</p>
<p>Array datatypes <b>cannot be subdivided for I/O</b>; the entire array must be transferred from one dataset to another.</p>
<p>Within certain limitations, outlined in the next paragraph, array datatypes may be N-dimensional and of any dimension size. <b>Unlimited dimensions, however, are not supported</b>. Functionality similar to unlimited dimension arrays is available through the use of variable-length datatypes.</p>
<p>The maximum number of dimensions, i.e., the maximum rank, of an array datatype is specified by the HDF5 library constant <a class="el" href="_h5_spublic_8h.html#a265cb2343f05cb71831119c90de31a8f">H5S_MAX_RANK</a>. The minimum rank is 1 (one). All dimension sizes must be greater than 0 (zero).</p>
<p>One array datatype may only be converted to another array datatype if the number of dimensions and the sizes of the dimensions are equal and the datatype of the first array's elements can be converted to the datatype of the second array's elements.</p>
<h3><a class="anchor" id="subsubsecLBDtypeSpecArrAPI"></a>
Array Datatype APIs</h3>
<p>There are three functions that are specific to array datatypes: one, <a class="el" href="group___a_r_r_a_y.html#ga39d41fdef06b3d7972ec2eab16ab5e96">H5Tarray_create</a>, for creating an array datatype, and two, <a class="el" href="group___a_r_r_a_y.html#gadec89de23da8efaba4677abfd818a9c0" title="Returns the rank of an array datatype.">H5Tget_array_ndims</a> and <a class="el" href="group___a_r_r_a_y.html#ga2b4fecf95c9c16e4431d8aba60995473">H5Tget_array_dims</a> for working with existing array datatypes.</p>
<h4>Creating</h4>
<p>The function <a class="el" href="group___a_r_r_a_y.html#ga39d41fdef06b3d7972ec2eab16ab5e96">H5Tarray_create</a> creates a new array datatype object. Parameters specify </p><ul>
<li>the base datatype of each element of the array, </li>
<li>the rank of the array, i.e., the number of dimensions, </li>
<li>the size of each dimension, and </li>
<li>the dimension permutation of the array, i.e., whether the elements of the array are listed in C or FORTRAN order.</li>
</ul>
<h4>Working with existing array datatypes</h4>
<p>When working with existing arrays, one must first determine the rank, or number of dimensions, of the array.</p>
<p>The function <a class="el" href="group___a_r_r_a_y.html#ga2b4fecf95c9c16e4431d8aba60995473">H5Tget_array_dims</a> returns the rank of a specified array datatype.</p>
<p>In many instances, one needs further information. The function <a class="el" href="group___a_r_r_a_y.html#ga2b4fecf95c9c16e4431d8aba60995473">H5Tget_array_dims</a> retrieves the permutation of the array and the size of each dimension.</p>
<h2><a class="anchor" id="subsecLBDtypeSpecCmpd"></a>
Compound</h2>
<h3><a class="anchor" id="subsubsecLBDtypeSpecCmpdProp"></a>
Properties of compound datatypes</h3>
<p>A compound datatype is similar to a struct in C or a common block in Fortran. It is a collection of one or more atomic types or small arrays of such types. To create and use of a compound datatype you need to refer to various properties of the data compound datatype: </p><ul>
<li>It is of class compound. </li>
<li>It has a fixed total size, in bytes. </li>
<li>It consists of zero or more members (defined in any order) with unique names and which occupy non-overlapping regions within the datum. </li>
<li>Each member has its own datatype. </li>
<li>Each member is referenced by an index number between zero and N-1, where N is the number of members in the compound datatype. </li>
<li>Each member has a name which is unique among its siblings in a compound datatype. </li>
<li>Each member has a fixed byte offset, which is the first byte (smallest byte address) of that member in a compound datatype. </li>
<li>Each member can be a small array of up to four dimensions.</li>
</ul>
<p>Properties of members of a compound datatype are defined when the member is added to the compound type and cannot be subsequently modified.</p>
<h3><a class="anchor" id="subsubsecLBDtypeSpecCmpdDef"></a>
Defining compound datatypes</h3>
<p>Compound datatypes must be built out of other datatypes. First, one creates an empty compound datatype and specifies its total size. Then members are added to the compound datatype in any order.</p>
<p>Member names. Each member must have a descriptive name, which is the key used to uniquely identify the member within the compound datatype. A member name in an HDF5 datatype does not necessarily have to be the same as the name of the corresponding member in the C struct in memory, although this is often the case. Nor does one need to define all members of the C struct in the HDF5 compound datatype (or vice versa).</p>
<p>Offsets. Usually a C struct will be defined to hold a data point in memory, and the offsets of the members in memory will be the offsets of the struct members from the beginning of an instance of the struct. The library defines the macro to compute the offset of a member within a struct: </p><div class="fragment"><div class="line"><a class="code hl_define" href="_h5_tpublic_8h.html#af5242159129a7f37ab85d33d85a1ccac">HOFFSET</a>(s,m)</div>
<div class="ttc" id="a_h5_tpublic_8h_html_af5242159129a7f37ab85d33d85a1ccac"><div class="ttname"><a href="_h5_tpublic_8h.html#af5242159129a7f37ab85d33d85a1ccac">HOFFSET</a></div><div class="ttdeci">#define HOFFSET(S, M)</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:22</div></div>
</div><!-- fragment --><p> This macro computes the offset of member m within a struct variable s.</p>
<p>Here is an example in which a compound datatype is created to describe complex numbers whose type is defined by the complex_t struct. </p><div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span>{</div>
<div class="line"> <span class="keywordtype">double</span> re; <span class="comment">/*real part */</span></div>
<div class="line"> <span class="keywordtype">double</span> im; <span class="comment">/*imaginary part */</span></div>
<div class="line">} complex_t;</div>
<div class="line"> </div>
<div class="line">complex_t tmp; <span class="comment">/*used only to compute offsets */</span></div>
<div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> complex_id = <a class="code hl_function" href="group___h5_t.html#gaa9afc38e1a7d35e4d0bec24c569b3c65">H5Tcreate</a> (<a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a7a401c61604dc846dbd3f9eb6fcb0fe6">H5T_COMPOUND</a>, <span class="keyword">sizeof</span> tmp);</div>
<div class="line"><a class="code hl_function" href="group___c_o_m_p_o_u_n_d.html#ga487d8f64a76f48b6eeb7f402d3b8b081">H5Tinsert</a> (complex_id, <span class="stringliteral">"real"</span>, <a class="code hl_define" href="_h5_tpublic_8h.html#af5242159129a7f37ab85d33d85a1ccac">HOFFSET</a>(tmp,re), <a class="code hl_define" href="group___p_d_t_n_a_t.html#ga087f3b793a299e416bd68678c2ef7c09">H5T_NATIVE_DOUBLE</a>);</div>
<div class="line"><a class="code hl_function" href="group___c_o_m_p_o_u_n_d.html#ga487d8f64a76f48b6eeb7f402d3b8b081">H5Tinsert</a> (complex_id, <span class="stringliteral">"imaginary"</span>, <a class="code hl_define" href="_h5_tpublic_8h.html#af5242159129a7f37ab85d33d85a1ccac">HOFFSET</a>(tmp,im), <a class="code hl_define" href="group___p_d_t_n_a_t.html#ga087f3b793a299e416bd68678c2ef7c09">H5T_NATIVE_DOUBLE</a>);</div>
<div class="ttc" id="a_h5_tpublic_8h_html_a071841985f647f69516dbe77d93167f2a7a401c61604dc846dbd3f9eb6fcb0fe6"><div class="ttname"><a href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a7a401c61604dc846dbd3f9eb6fcb0fe6">H5T_COMPOUND</a></div><div class="ttdeci">@ H5T_COMPOUND</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:38</div></div>
<div class="ttc" id="agroup___c_o_m_p_o_u_n_d_html_ga487d8f64a76f48b6eeb7f402d3b8b081"><div class="ttname"><a href="group___c_o_m_p_o_u_n_d.html#ga487d8f64a76f48b6eeb7f402d3b8b081">H5Tinsert</a></div><div class="ttdeci">herr_t H5Tinsert(hid_t parent_id, const char *name, size_t offset, hid_t member_id)</div><div class="ttdoc">Adds a new member to a compound datatype.</div></div>
<div class="ttc" id="agroup___h5_t_html_gaa9afc38e1a7d35e4d0bec24c569b3c65"><div class="ttname"><a href="group___h5_t.html#gaa9afc38e1a7d35e4d0bec24c569b3c65">H5Tcreate</a></div><div class="ttdeci">hid_t H5Tcreate(H5T_class_t type, size_t size)</div><div class="ttdoc">Creates a new datatype.</div></div>
<div class="ttc" id="agroup___p_d_t_n_a_t_html_ga087f3b793a299e416bd68678c2ef7c09"><div class="ttname"><a href="group___p_d_t_n_a_t.html#ga087f3b793a299e416bd68678c2ef7c09">H5T_NATIVE_DOUBLE</a></div><div class="ttdeci">#define H5T_NATIVE_DOUBLE</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:802</div></div>
</div><!-- fragment --><h2><a class="anchor" id="subsecLBDtypeSpecRef"></a>
Reference</h2>
<p>There are two types of Reference datatypes in HDF5: </p><ul>
<li><a class="el" href="#subsubsecLBDtypeSpecRefObj">Reference to objects</a> </li>
<li><a class="el" href="#subsubsecLBDtypeSpecRefDset">Reference to a dataset region</a></li>
</ul>
<h3><a class="anchor" id="subsubsecLBDtypeSpecRefObj"></a>
Reference to objects</h3>
<p>In HDF5, objects (i.e. groups, datasets, and named datatypes) are usually accessed by name. There is another way to access stored objects – by reference.</p>
<p>An object reference is based on the relative file address of the object header in the file and is constant for the life of the object. Once a reference to an object is created and stored in a dataset in the file, it can be used to dereference the object it points to. References are handy for creating a file index or for grouping related objects by storing references to them in one dataset.</p>
<h4>Creating and storing references to objects</h4>
<p>The following steps are involved in creating and storing file references to objects: </p><ol>
<li>
Create the objects or open them if they already exist in the file. </li>
<li>
Create a dataset to store the objects' references, by specifying <a class="el" href="group___p_d_t_s_t_d.html#gadc17e0960dc7ef08e029bf17201670e1">H5T_STD_REF_OBJ</a> as the datatype </li>
<li>
Create and store references to the objects in a buffer, using <a class="el" href="group___h5_r.html#ga0ac6997b5de26b11d91a95de2869950d" title="Creates a reference.">H5Rcreate</a>. </li>
<li>
Write a buffer with the references to the dataset, using <a class="el" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906" title="Writes raw data from a buffer to a dataset.">H5Dwrite</a> with the <a class="el" href="group___p_d_t_s_t_d.html#gadc17e0960dc7ef08e029bf17201670e1">H5T_STD_REF_OBJ</a> datatype. </li>
</ol>
<h4>Reading references and accessing objects using references</h4>
<p>The following steps are involved: </p><ol>
<li>
Open the dataset with the references and read them. The <a class="el" href="group___p_d_t_s_t_d.html#gadc17e0960dc7ef08e029bf17201670e1">H5T_STD_REF_OBJ</a> datatype must be used to describe the memory datatype. </li>
<li>
Use the read reference to obtain the identifier of the object the reference points to using <a class="el" href="group___h5_r.html#ga5dc19b9d1833af66c5e1f819f2c05c4a">H5Rdereference</a>. </li>
<li>
Open the dereferenced object and perform the desired operations. </li>
<li>
Close all objects when the task is complete. </li>
</ol>
<h3><a class="anchor" id="subsubsecLBDtypeSpecRefDset"></a>
Reference to a dataset region</h3>
<p>A dataset region reference points to a dataset selection in another dataset. A reference to the dataset selection (region) is constant for the life of the dataset.</p>
<h4>Creating and storing references to dataset regions</h4>
<p>The following steps are involved in creating and storing references to a dataset region: </p><ul>
<li>Create a dataset to store the dataset region (selection), by passing in <a class="el" href="group___p_d_t_s_t_d.html#gaf5cb0d5cec3d40d8b3ac27512f86895e">H5T_STD_REF_DSETREG</a> for the datatype when calling <a class="el" href="group___h5_d.html#ga0647ba4bbd26d5230cc07f3a5685b2cf">H5Dcreate</a>. </li>
<li>Create selection(s) in existing dataset(s) using <a class="el" href="group___h5_s.html#ga6adfdf1b95dc108a65bf66e97d38536d" title="Selects a hyperslab region to add to the current selected region.">H5Sselect_hyperslab</a> and/or <a class="el" href="group___h5_s.html#ga2f4407dd73d0ec37e5d9e80e4382483d" title="Selects array elements to be included in the selection for a dataspace.">H5Sselect_elements</a>. </li>
<li>Create reference(s) to the selection(s) using <a class="el" href="group___h5_r.html#ga0ac6997b5de26b11d91a95de2869950d" title="Creates a reference.">H5Rcreate</a> and store them in a buffer. </li>
<li>Write the references to the dataset regions in the file. </li>
<li>Close all objects.</li>
</ul>
<h4>Reading references to dataset regions</h4>
<p>The following steps are involved in reading references to dataset regions and referenced dataset regions (selections). </p><ol>
<li>
Open and read the dataset containing references to the dataset regions. The datatype <a class="el" href="group___p_d_t_s_t_d.html#gaf5cb0d5cec3d40d8b3ac27512f86895e">H5T_STD_REF_DSETREG</a> must be used during read operation. </li>
<li>
Use <a class="el" href="group___h5_r.html#ga5dc19b9d1833af66c5e1f819f2c05c4a">H5Rdereference</a> to obtain the dataset identifier from the read dataset region reference. OR Use <a class="el" href="group___h5_r.html#ga1702d609e85b9edd3d1e526a0276484f" title="Sets up a dataspace and selection as specified by a region reference.">H5Rget_region</a> to obtain the dataspace identifier for the dataset containing the selection from the read dataset region reference. </li>
<li>
With the dataspace identifier, the <a class="el" href="group___h5_s.html">Dataspaces (H5S)</a> interface functions, H5Sget_select_*, can be used to obtain information about the selection. </li>
<li>
Close all objects when they are no longer needed. </li>
</ol>
<p>The dataset with the region references was read by <a class="el" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c" title="Reads raw data from a dataset into a provided buffer.">H5Dread</a> with the <a class="el" href="group___p_d_t_s_t_d.html#gaf5cb0d5cec3d40d8b3ac27512f86895e">H5T_STD_REF_DSETREG</a> datatype specified.</p>
<p>The read reference can be used to obtain the dataset identifier by calling <a class="el" href="group___h5_r.html#ga5dc19b9d1833af66c5e1f819f2c05c4a">H5Rdereference</a> or by obtaining obtain spatial information (dataspace and selection) with the call to <a class="el" href="group___h5_r.html#ga1702d609e85b9edd3d1e526a0276484f" title="Sets up a dataspace and selection as specified by a region reference.">H5Rget_region</a>.</p>
<p>The reference to the dataset region has information for both the dataset itself and its selection. In both functions: </p><ul>
<li>The first parameter is an identifier of the dataset with the region references. </li>
<li>The second parameter specifies the type of reference stored. In this example, a reference to the dataset region is stored. </li>
<li>The third parameter is a buffer containing the reference of the specified type.</li>
</ul>
<p>This example introduces several H5Sget_select_* functions used to obtain information about selections: </p><table class="doxtable">
<caption>Examples of HDF5 predefined datatypes</caption>
<tr>
<th><b>Function</b> </th><th><b>Description</b> </th></tr>
<tr>
<td><a class="el" href="group___h5_s.html#ga1a44dde97206f40f366f99d9c39b6046" title="Determines the number of elements in a dataspace selection.">H5Sget_select_npoints</a> </td><td>Returns the number of elements in the hyperslab </td></tr>
<tr>
<td><a class="el" href="group___h5_s.html#gad873b2f3b82ee8c426c26ceeb1c67f86" title="Get number of hyperslab blocks.">H5Sget_select_hyper_nblocks</a> </td><td>Returns the number of blocks in the hyperslab </td></tr>
<tr>
<td><a class="el" href="group___h5_s.html#ga8534829a8db2eca8e987bb9fe8a3d628" title="Gets the list of hyperslab blocks currently selected.">H5Sget_select_hyper_blocklist</a> </td><td>Returns the "lower left" and "upper right" coordinates of the blocks in the hyperslab selection </td></tr>
<tr>
<td><a class="el" href="group___h5_s.html#ga645591ec939b89732c10efd5867a6205" title="Gets the bounding box containing the current selection.">H5Sget_select_bounds</a> </td><td>Returns the coordinates of the "minimal" block containing a hyperslab selection </td></tr>
<tr>
<td><a class="el" href="group___h5_s.html#ga217b839584cd7c7995b47fc30fe92f4c" title="Gets the number of element points in the current selection.">H5Sget_select_elem_npoints</a> </td><td>Returns the number of points in the element selection </td></tr>
<tr>
<td><a class="el" href="group___h5_s.html#ga61459c488147254d1d06537a9ab6e2d4" title="Gets the list of element points currently selected.">H5Sget_select_elem_pointlist</a> </td><td>Returns the coordinates of points in the element selection </td></tr>
</table>
<h2><a class="anchor" id="subsecLBDtypeSpecStr"></a>
String</h2>
<p>A simple example of creating a derived datatype is using the string datatype, <a class="el" href="group___p_d_t_s.html#ga7f6b6959fefe56d2e871659110936d2d">H5T_C_S1</a> (<a class="el" href="group___p_d_t_s.html#ga62335f6f57c2809fa1b3b1f9472eb2f6">H5T_FORTRAN_S1</a>) to create strings of more than one character. Strings can be stored as either fixed or variable length, and may have different rules for padding of unused storage.</p>
<h3><a class="anchor" id="subsecLBDtypeSpecStrFix"></a>
Fixed Length 5-character String Datatype</h3>
<div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> strtype; <span class="comment">/* Datatype ID */</span></div>
<div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> status;</div>
<div class="line"> </div>
<div class="line">strtype = <a class="code hl_function" href="group___h5_t.html#gaec07efbab84f4e5b4ed22f010786be8e">H5Tcopy</a> (<a class="code hl_define" href="group___p_d_t_s.html#ga7f6b6959fefe56d2e871659110936d2d">H5T_C_S1</a>);</div>
<div class="line">status = <a class="code hl_function" href="group___h5_t.html#gae5f38bfd4a4c557496b3194b5180212c">H5Tset_size</a> (strtype, 5); <span class="comment">/* create string of length 5 */</span></div>
<div class="ttc" id="agroup___h5_t_html_gae5f38bfd4a4c557496b3194b5180212c"><div class="ttname"><a href="group___h5_t.html#gae5f38bfd4a4c557496b3194b5180212c">H5Tset_size</a></div><div class="ttdeci">herr_t H5Tset_size(hid_t type_id, size_t size)</div><div class="ttdoc">Sets size for a datatype.</div></div>
<div class="ttc" id="agroup___p_d_t_s_html_ga7f6b6959fefe56d2e871659110936d2d"><div class="ttname"><a href="group___p_d_t_s.html#ga7f6b6959fefe56d2e871659110936d2d">H5T_C_S1</a></div><div class="ttdeci">#define H5T_C_S1</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:476</div></div>
</div><!-- fragment --><h3><a class="anchor" id="subsecLBDtypeSpecStrVar"></a>
Variable Length String Datatype</h3>
<div class="fragment"><div class="line">strtype = <a class="code hl_function" href="group___h5_t.html#gaec07efbab84f4e5b4ed22f010786be8e">H5Tcopy</a> (<a class="code hl_define" href="group___p_d_t_s.html#ga7f6b6959fefe56d2e871659110936d2d">H5T_C_S1</a>);</div>
<div class="line">status = <a class="code hl_function" href="group___h5_t.html#gae5f38bfd4a4c557496b3194b5180212c">H5Tset_size</a> (strtype, <a class="code hl_define" href="_h5_tpublic_8h.html#a5185e14efde13b48249fe391324331bc">H5T_VARIABLE</a>);</div>
<div class="ttc" id="a_h5_tpublic_8h_html_a5185e14efde13b48249fe391324331bc"><div class="ttname"><a href="_h5_tpublic_8h.html#a5185e14efde13b48249fe391324331bc">H5T_VARIABLE</a></div><div class="ttdeci">#define H5T_VARIABLE</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:207</div></div>
</div><!-- fragment --><p>The ability to derive datatypes from pre-defined types allows users to create any number of datatypes, from simple to very complex.</p>
<p>As the term implies, variable length strings are strings of varying lengths. They are stored internally in a heap, potentially impacting efficiency in the following ways: </p><ul>
<li>Heap storage requires more space than regular raw data storage. </li>
<li>Heap access generally reduces I/O efficiency because it requires individual read or write operations for each data element rather than one read or write per dataset or per data selection. </li>
<li>A variable length dataset consists of pointers to the heaps of data, not the actual data. Chunking and filters, including compression, are not available for heaps.</li>
</ul>
<p>See <a class="el" href="_h5_t__u_g.html#subsubsec_datatype_other_strings">Strings</a> in the <a class="el" href="_u_g.html">HDF5 User Guide</a>, for more information on how fixed and variable length strings are stored.</p>
<h2><a class="anchor" id="subsecLBDtypeSpecVL"></a>
Variable Length</h2>
<p>Variable-length (VL) datatypes are sequences of an existing datatype (atomic, VL, or compound) which are not fixed in length from one dataset location to another. In essence, they are similar to C character strings – a sequence of a type which is pointed to by a particular type of pointer – although they are implemented more closely to FORTRAN strings by including an explicit length in the pointer instead of using a particular value to terminate the sequence.</p>
<p>VL datatypes are useful to the scientific community in many different ways, some of which are listed below: </p><ul>
<li>
Ragged arrays: Multi-dimensional ragged arrays can be implemented with the last (fastest changing) dimension being ragged by using a VL datatype as the type of the element stored. (Or as a field in a compound datatype.) </li>
<li>
Fractal arrays: If a compound datatype has a VL field of another compound type with VL fields (a nested VL datatype), this can be used to implement ragged arrays of ragged arrays, to whatever nesting depth is required for the user. </li>
<li>
Polygon lists: A common storage requirement is to efficiently store arrays of polygons with different numbers of vertices. VL datatypes can be used to efficiently and succinctly describe an array of polygons with different numbers of vertices. </li>
<li>
Character strings: Perhaps the most common use of VL datatypes will be to store C-like VL character strings in dataset elements or as attributes of objects. </li>
<li>
Indices: An array of VL object references could be used as an index to all the objects in a file which contain a particular sequence of dataset values. Perhaps an array something like the following: <div class="fragment"><div class="line">Value1: Object1, Object3, Object9</div>
<div class="line">Value2: Object0, Object12, Object14, Object21, Object22</div>
<div class="line">Value3: Object2</div>
<div class="line">Value4: <none></div>
<div class="line">Value5: Object1, Object10, Object12</div>
<div class="line"> .</div>
<div class="line"> .</div>
</div><!-- fragment --> </li>
<li>
Object Tracking: An array of VL dataset region references can be used as a method of tracking objects or features appearing in a sequence of datasets. Perhaps an array of them would look like: <div class="fragment"><div class="line">Feature1: Dataset1:Region, Dataset3:Region, Dataset9:Region</div>
<div class="line">Feature2: Dataset0:Region, Dataset12:Region, Dataset14:Region,</div>
<div class="line"> Dataset21:Region, Dataset22:Region</div>
<div class="line">Feature3: Dataset2:Region</div>
<div class="line">Feature4: <none></div>
<div class="line">Feature5: Dataset1:Region, Dataset10:Region, Dataset12:Region</div>
<div class="line"> .</div>
<div class="line"> .</div>
</div><!-- fragment --> </li>
</ul>
<h3><a class="anchor" id="subsubsecLBDtypeSpecVLMem"></a>
Variable-length datatype memory management</h3>
<p>With each element possibly being of different sequence lengths for a dataset with a VL datatype, the memory for the VL datatype must be dynamically allocated. Currently there are two methods of managing the memory for VL datatypes: the standard C malloc/free memory allocation routines or a method of calling user-defined memory management routines to allocate or free memory. Since the memory allocated when reading (or writing) may be complicated to release, an HDF5 routine is provided to traverse a memory buffer and free the VL datatype information without leaking memory.</p>
<h3><a class="anchor" id="subsubsecLBDtypeSpecVLDiv"></a>
Variable-length datatypes cannot be divided</h3>
<p>VL datatypes are designed so that they cannot be subdivided by the library with selections, etc. This design was chosen due to the complexities in specifying selections on each VL element of a dataset through a selection API that is easy to understand. Also, the selection APIs work on dataspaces, not on datatypes. At some point in time, we may want to create a way for dataspaces to have VL components to them and we would need to allow selections of those VL regions, but that is beyond the scope of this document.</p>
<h3><a class="anchor" id="subsubsecLBDtypeSpecVLErr"></a>
What happens if the library runs out of memory while reading?</h3>
<p>It is possible for a call to <a class="el" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c" title="Reads raw data from a dataset into a provided buffer.">H5Dread</a> to fail while reading in VL datatype information if the memory required exceeds that which is available. In this case, the <a class="el" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c" title="Reads raw data from a dataset into a provided buffer.">H5Dread</a> call will fail gracefully and any VL data which has been allocated prior to the memory shortage will be returned to the system via the memory management routines detailed below. It may be possible to design a partial read API function at a later date, if demand for such a function warrants.</p>
<h3><a class="anchor" id="subsubsecLBDtypeSpecVLStr"></a>
Strings as variable-length datatypes</h3>
<p>Since character strings are a special case of VL data that is implemented in many different ways on different machines and in different programming languages, they are handled somewhat differently from other VL datatypes in HDF5.</p>
<p>HDF5 has native VL strings for each language API, which are stored the same way on disk, but are exported through each language API in a natural way for that language. When retrieving VL strings from a dataset, users may choose to have them stored in memory as a native VL string or in HDF5's <a class="el" href="structhvl__t.html">hvl_t</a> struct for VL datatypes.</p>
<p>VL strings may be created in one of two ways: by creating a VL datatype with a base type of <a class="el" href="group___p_d_t_s.html#ga7f6b6959fefe56d2e871659110936d2d">H5T_C_S1</a> and setting its length to <a class="el" href="_h5_tpublic_8h.html#a5185e14efde13b48249fe391324331bc">H5T_VARIABLE</a>. The second method is used to access native VL strings in memory. The library will convert between the two types, but they are stored on disk using different datatypes and have different memory representations.</p>
<p>Multi-byte character representations, such as <em>UNICODE</em> or <em>wide</em> characters in C/C++, will need the appropriate character and string datatypes created so that they can be described properly through the datatype API. Additional conversions between these types and the current ASCII characters will also be required.</p>
<p>Variable-width character strings (which might be compressed data or some other encoding) are not currently handled by this design. We will evaluate how to implement them based on user feedback.</p>
<h3><a class="anchor" id="subsubsecLBDtypeSpecVLAPIs"></a>
Variable-length datatype APIs</h3>
<h4>Creation</h4>
<p>VL datatypes are created with the <a class="el" href="group___v_l_e_n.html#ga6841355fa5b3c924876b121dedb8ed2f" title="Creates a new variable-length array datatype.">H5Tvlen_create</a> function as follows: </p><div class="fragment"><div class="line">type_id = <a class="code hl_function" href="group___v_l_e_n.html#ga6841355fa5b3c924876b121dedb8ed2f">H5Tvlen_create</a>(<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> base_type_id);</div>
<div class="ttc" id="agroup___v_l_e_n_html_ga6841355fa5b3c924876b121dedb8ed2f"><div class="ttname"><a href="group___v_l_e_n.html#ga6841355fa5b3c924876b121dedb8ed2f">H5Tvlen_create</a></div><div class="ttdeci">hid_t H5Tvlen_create(hid_t base_id)</div><div class="ttdoc">Creates a new variable-length array datatype.</div></div>
</div><!-- fragment --><p> The base datatype will be the datatype that the sequence is composed of, characters for character strings, vertex coordinates for polygon lists, etc. The base datatype specified for the VL datatype can be of any HDF5 datatype, including another VL datatype, a compound datatype, or an atomic datatype.</p>
<h4>Querying base datatype of VL datatype</h4>
<p>It may be necessary to know the base datatype of a VL datatype before memory is allocated, etc. The base datatype is queried with the <a class="el" href="group___h5_t.html#ga331e8f7b388a50af77294018db788de3" title="Returns the base datatype from which a datatype is derived.">H5Tget_super</a> function, described in the <a class="el" href="group___h5_t.html">Datatypes (H5T)</a> documentation.</p>
<h4>Querying minimum memory required for VL information</h4>
<p>It order to predict the memory usage that <a class="el" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c" title="Reads raw data from a dataset into a provided buffer.">H5Dread</a> may need to allocate to store VL data while reading the data, the <a class="el" href="group___h5_d.html#ga0e97bbd8a8ee4a8b5b78ccce8547ce76" title="Determines the number of bytes required to store variable-length (VL) data.">H5Dvlen_get_buf_size</a> function is provided: </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___h5_d.html#ga0e97bbd8a8ee4a8b5b78ccce8547ce76">H5Dvlen_get_buf_size</a>(<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> dataset_id, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> type_id, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> space_id, <a class="code hl_typedef" href="_h5public_8h.html#a7f81cce70fb546af88da24d9285d3c1c">hsize_t</a> *size)</div>
<div class="ttc" id="agroup___h5_d_html_ga0e97bbd8a8ee4a8b5b78ccce8547ce76"><div class="ttname"><a href="group___h5_d.html#ga0e97bbd8a8ee4a8b5b78ccce8547ce76">H5Dvlen_get_buf_size</a></div><div class="ttdeci">herr_t H5Dvlen_get_buf_size(hid_t dset_id, hid_t type_id, hid_t space_id, hsize_t *size)</div><div class="ttdoc">Determines the number of bytes required to store variable-length (VL) data.</div></div>
</div><!-- fragment --><p> This routine checks the number of bytes required to store the VL data from the dataset, using the <em>space_id</em> for the selection in the dataset on disk and the <em>type_id</em> for the memory representation of the VL data in memory. The *<em>size</em> value is modified according to how many bytes are required to store the VL data in memory.</p>
<h4>Specifying how to manage memory for the VL datatype</h4>
<p>The memory management method is determined by dataset transfer properties passed into the <a class="el" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c" title="Reads raw data from a dataset into a provided buffer.">H5Dread</a> and <a class="el" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906" title="Writes raw data from a buffer to a dataset.">H5Dwrite</a> functions with the dataset transfer property list.</p>
<p>Default memory management is set by using <a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a> for the dataset transfer property list identifier. If <a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a> is used with <a class="el" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c" title="Reads raw data from a dataset into a provided buffer.">H5Dread</a>, the system <em>malloc</em> and <em>free</em> calls will be used for allocating and freeing memory. In such a case, <a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a> should also be passed as the property list identifier to <a class="el" href="group___h5_d.html#ga222a2fd93868e2524b2e42c3c6146119" title="Reclaims variable-length (VL) datatype memory buffers.">H5Dvlen_reclaim</a>.</p>
<p>The rest of this subsection is relevant only to those who choose not to use default memory management.</p>
<p>The user can choose whether to use the system <em>malloc</em> and <em>free</em> calls or user-defined, or custom, memory management functions. If user-defined memory management functions are to be used, the memory allocation and free routines must be defined via <a class="el" href="group___d_x_p_l.html#ga2220ab75de470b6a6d5b1173d12aa0cf" title="Sets the memory manager for variable-length datatype allocation in H5Dread() and H5Dvlen_reclaim()">H5Pset_vlen_mem_manager()</a>, as follows: </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___d_x_p_l.html#ga2220ab75de470b6a6d5b1173d12aa0cf">H5Pset_vlen_mem_manager</a>(<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> plist_id, <a class="code hl_typedef" href="_h5_m_mpublic_8h.html#a5fd832e4b7f42f93364153cb823e7ffa">H5MM_allocate_t</a> alloc, <span class="keywordtype">void</span> *alloc_info, <a class="code hl_typedef" href="_h5_m_mpublic_8h.html#aa34c7616be59673cfc3d63fa7d960f25">H5MM_free_t</a> free, <span class="keywordtype">void</span> *free_info)</div>
<div class="ttc" id="a_h5_m_mpublic_8h_html_a5fd832e4b7f42f93364153cb823e7ffa"><div class="ttname"><a href="_h5_m_mpublic_8h.html#a5fd832e4b7f42f93364153cb823e7ffa">H5MM_allocate_t</a></div><div class="ttdeci">void *(* H5MM_allocate_t)(size_t size, void *alloc_info)</div><div class="ttdef"><b>Definition</b> H5MMpublic.h:29</div></div>
<div class="ttc" id="a_h5_m_mpublic_8h_html_aa34c7616be59673cfc3d63fa7d960f25"><div class="ttname"><a href="_h5_m_mpublic_8h.html#aa34c7616be59673cfc3d63fa7d960f25">H5MM_free_t</a></div><div class="ttdeci">void(* H5MM_free_t)(void *mem, void *free_info)</div><div class="ttdef"><b>Definition</b> H5MMpublic.h:33</div></div>
<div class="ttc" id="agroup___d_x_p_l_html_ga2220ab75de470b6a6d5b1173d12aa0cf"><div class="ttname"><a href="group___d_x_p_l.html#ga2220ab75de470b6a6d5b1173d12aa0cf">H5Pset_vlen_mem_manager</a></div><div class="ttdeci">herr_t H5Pset_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t alloc_func, void *alloc_info, H5MM_free_t free_func, void *free_info)</div><div class="ttdoc">Sets the memory manager for variable-length datatype allocation in H5Dread() and H5Dvlen_reclaim()</div></div>
</div><!-- fragment --><p> The <em>alloc</em> and <em>free</em> parameters identify the memory management routines to be used. If the user has defined custom memory management routines, <em>alloc</em> and/or <em>free</em> should be set to make those routine calls (i.e., the name of the routine is used as the value of the parameter); if the user prefers to use the system's <em>malloc</em> and/or <em>free</em>, the <em>alloc</em> and <em>free</em> parameters, respectively, should be set to <em>NULL</em> </p>
<p>The prototypes for the user-defined functions would appear as follows: </p><div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keywordtype">void</span> *(*H5MM_allocate_t)(<span class="keywordtype">size_t</span> size, <span class="keywordtype">void</span> *info) ; <span class="keyword">typedef</span> void (*<a class="code hl_typedef" href="_h5_m_mpublic_8h.html#aa34c7616be59673cfc3d63fa7d960f25">H5MM_free_t</a>)(<span class="keywordtype">void</span> *mem, <span class="keywordtype">void</span> *free_info) ;</div>
</div><!-- fragment --><p> The <em>alloc_info</em> and <em>free_info</em> parameters can be used to pass along any required information to the user's memory management routines.</p>
<p>In summary, if the user has defined custom memory management routines, the name(s) of the routines are passed in the <em>alloc</em> and <em>free</em> parameters and the custom routines' parameters are passed in the <em>alloc_info</em> and <em>free_info</em> parameters. If the user wishes to use the system <em>malloc</em> and <em>free</em> functions, the <em>alloc</em> and/or <em>free</em> parameters are set to <em>NULL</em> and the <em>alloc_info</em> and <em>free_info</em> parameters are ignored.</p>
<h4>Recovering memory from VL buffers read in</h4>
<p>The complex memory buffers created for a VL datatype may be reclaimed with the <a class="el" href="group___h5_d.html#ga222a2fd93868e2524b2e42c3c6146119" title="Reclaims variable-length (VL) datatype memory buffers.">H5Dvlen_reclaim</a> function call, as follows: </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___h5_d.html#ga222a2fd93868e2524b2e42c3c6146119">H5Dvlen_reclaim</a>(<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> type_id, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> space_id, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> plist_id, <span class="keywordtype">void</span> *buf);</div>
<div class="ttc" id="agroup___h5_d_html_ga222a2fd93868e2524b2e42c3c6146119"><div class="ttname"><a href="group___h5_d.html#ga222a2fd93868e2524b2e42c3c6146119">H5Dvlen_reclaim</a></div><div class="ttdeci">herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf)</div><div class="ttdoc">Reclaims variable-length (VL) datatype memory buffers.</div></div>
</div><!-- fragment --><p>The <em>type_id</em> must be the datatype stored in the buffer, <em>space_id</em> describes the selection for the memory buffer to free the VL datatypes within, <em>plist_id</em> is the dataset transfer property list which was used for the I/O transfer to create the buffer, and <em>buf</em> is the pointer to the buffer to free the VL memory within. The VL structures (<a class="el" href="structhvl__t.html">hvl_t</a>) in the user's buffer are modified to zero out the VL information after it has been freed.</p>
<p>If nested VL datatypes were used to create the buffer, this routine frees them from the bottom up, releasing all the memory without creating memory leaks.</p>
<hr />
<p> Navigate back: <a class="el" href="index.html">Main</a> / <a class="el" href="_getting_started.html">Getting Started with HDF5</a> / <a class="el" href="_learn_basics.html">Learning the Basics</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.10.0 </li>
</ul>
</div>
</body>
</html>
|
